How to Set Up a New Project for Claude Code (AGENTS.md, Subagents, and Slash Commands)

TL;DR

A good setup for an AI coding agent is three pieces working together: an AGENTS.md rules file (how to work in your repo), a subagent in .claude/agents/ (a focused helper the main agent delegates to), and a slash command in .claude/commands/ (your most-typed prompt, one keystroke away). This post walks through all three with verified formats and real examples. Want them generated for you? The free AI agent project starter kit builds the whole set from a form.

Why one config file isn't enough

Most "set up your AI agent" advice stops at the rules file. That's the foundation, but a productive setup has two more pieces:

The rules file tells the agent how to work in your project.
A subagent lets it delegate noisy subtasks (code review, tests, repo exploration) without clogging the main thread.
A slash command turns your most-repeated prompt into a reusable shortcut.

Together they take you from "an agent that needs re-explaining every session" to "an agent that knows your project and has your common workflows on tap." Here's how to set up each — and how they fit together.

Step 1 — The rules file (AGENTS.md)

This is the foundation: a plain-markdown file at your repo root that tells the agent your stack, commands, conventions, and anti-patterns. It has no frontmatter — just structured markdown.

A thin example:

# My Project

> Next.js + Postgres app. Read this before making changes.

## Tech stack
- TypeScript, Next.js 16 (App Router), Drizzle ORM, Postgres
- Package manager: pnpm

## Commands
| Task | Command |
| --- | --- |
| Build | `pnpm verify` |
| Test | `pnpm test` |

## Conventions
- Server Components fetch directly from the DB.
- API responses whitelist fields; never spread the whole row.

## Anti-patterns — don't
- Don't expose PII in URLs or client bundles.
- Don't trust client-side validation alone.

That's the whole shape. For the full treatment — the five rules, the common mistakes — see How to Write a Great AGENTS.md, or generate one with the free AGENTS.md generator.

CLAUDE.md is the same file with the name Claude Code reads first; AGENTS.md is the cross-tool convention. Pick based on your tools.

Step 2 — A subagent (.claude/agents/)

A subagent is a separate agent the main one can spin up for a focused task. It works in its own context window and returns a short result — so noisy work (reviewing a diff, exploring the repo, writing tests) doesn't fill your main thread.

Subagents are markdown files in .claude/agents/ with YAML frontmatter. Only name and description are required; tools and model are optional. The body becomes the subagent's system prompt.

A code-reviewer subagent (.claude/agents/code-reviewer.md):

---
name: code-reviewer
description: Reviews code changes for bugs, security, and style. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a skeptical senior staff engineer reviewing a change.

Rank issues by severity. For each, give: what's wrong, why it matters,
and the smallest fix. Check edge cases, error handling, secret/PII
leaks, N+1 queries, and anything that contradicts AGENTS.md. Be blunt.
If the change is clean, say so in one line — don't invent nitpicks.

The description is what the main agent reads to decide when to delegate to this subagent, so make it specific. Good first subagents: a code reviewer, a test writer, or a repo explorer that returns a brief instead of dumping search output into your main thread.

Step 3 — A slash command (.claude/commands/)

A slash command is a reusable prompt template you invoke with /name. Pick the paragraph you re-type most and turn it into one keystroke.

Commands are markdown files in .claude/commands/, where the filename becomes the command name. Frontmatter is optional: description, allowed-tools, argument-hint. The body is the prompt, and $ARGUMENTS (or $1, $2) captures what you pass after the command.

A /review command (.claude/commands/review.md):

---
description: Review a file or directory for bugs, security, and style.
allowed-tools: Read, Grep, Glob
argument-hint: [path]
---

Review $ARGUMENTS like a skeptical senior staff engineer.

Rank issues by severity. For each: what's wrong, why it matters, the
smallest fix. Check edge cases, error handling, secret/PII leaks, and
anything that contradicts AGENTS.md. Be blunt; if it's clean, say so.

Now /review src/lib/payments.ts runs that whole prompt against the path. Good first commands: /review, /test, and /commit (generate a Conventional Commit message for staged changes).

How the three work together

Here's the payoff — a real workflow once all three exist:

You ask the agent to build a feature. It reads AGENTS.md and writes code that matches your conventions on the first pass.
You run /review src/feature/ — your slash command kicks off a focused review.
Under the hood the main agent delegates to the code-reviewer subagent, which reviews in its own context and returns a tight list of issues — without flooding your main thread.

That's the difference between an agent you constantly correct and one that's set up to do your common work the way you'd do it.

Do it in two minutes

You can hand-write all three from the examples above. Or use the free AI agent project starter kit: fill in your stack and pick a subagent and command, and it generates the rules file, the subagent, and the slash command together — in the correct paths — plus a one-paste setup script that scaffolds the whole .claude/ directory at once. No install, no AI tokens, runs in your browser.

Common mistakes

Stopping at the rules file. It's the foundation, not the whole setup. The subagent and command are where the daily leverage is.
Vague subagent descriptions. The main agent uses the description to decide when to delegate. "Helps with code" won't trigger reliably; "Reviews code changes after you write them" will.
Commands that don't take arguments. A /review that can't take a path is half a command. Use $ARGUMENTS.
Not checking them into version control. Put .claude/ in git so your team shares the same setup and can improve it together.
Letting them drift. Like AGENTS.md, update subagents and commands when your conventions change.

What to do next

Write (or generate) the three files for a project you're actively working on.
Start with a code-reviewer subagent and a /review command — the highest-leverage pair.
Commit .claude/ so it's shared and version-controlled.
Add a new command whenever you catch yourself re-typing the same prompt twice.

The underlying idea is the same one behind spec-driven AI: the agent isn't the bottleneck — setting it up to know your project and your workflows is.