Tutorials
Organize Claude Code for Product Work: 7-Step Setup
A practical setup guide for running Claude Code on real product teams: repo layout, CLAUDE.md, custom slash commands, and PR-ready workflows.
August 11, 2026
Most Claude Code demos show a solo dev shipping a todo app in fifteen minutes. Real product work looks nothing like that. You're juggling half-baked specs, three services, a design review, and a PM who wants the feature yesterday.
And that's where the tool starts to bend. Not because Claude Code is weak (developer sentiment on the tool remains broadly positive), but because most teams drop it into a repo with zero scaffolding and expect magic. The organizational layer is the whole game.
This tutorial walks through a battle-tested setup for using Claude Code on a real product codebase. It's adapted from the recent Hacker News discussion around The AI Thinker's guide, plus patterns pulled from Anthropic's own engineering team.
What you'll build
By the end of this guide, you'll have:
- A
CLAUDE.mdfile that actually shapes agent behavior instead of getting ignored - A
.claude/directory with custom slash commands for repeatable workflows - A spec-first pattern that keeps Claude Code from wandering off
- A PR review loop that catches its worst habits before human reviewers do
The whole setup takes about 45 minutes to bootstrap. You do it once per repo, and the ROI compounds every sprint after.
Prerequisites
You'll need:
- Claude Code installed (
npm install -g @anthropic-ai/claude-code) - An active Anthropic API key or Claude Max subscription
- A real product repository (this pattern doesn't shine on toy projects)
- Node.js 22 or later (this is the current requirement per Anthropic's setup docs)
- Git configured with a branch protection rule for
main(trust me on this one)
If you're on Windows, use WSL2. Native Windows works, but the file-watching behavior is flaky in monorepos.
Step 1: Write a CLAUDE.md that isn't garbage
CLAUDE.md is the first file Claude Code reads when it enters a repo. Most teams treat it like a README. That's a mistake. Treat CLAUDE.md as a system prompt scoped to your codebase.
Create it at the repo root:
Bash
touch CLAUDE.md
A good CLAUDE.md has five sections, in this order:
Markdown
# Project: Acme Billing Service
## Purpose
One-paragraph answer to "what does this repo do and who uses it."
## Architecture
- Runtime: Node 20, TypeScript strict mode
- Framework: Fastify + Prisma + PostgreSQL 16
- Deploy: Fly.io, promoted via GitHub Actions on merge to main
## Conventions
- Use `pnpm`, never `npm` or `yarn`
- All routes live in `src/routes/`, one file per resource
- Never edit `prisma/migrations/` by hand — generate them
- Tests use Vitest, colocated as `*.test.ts`
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
## Boundaries
- Do NOT touch `src/legacy/` without explicit permission
- Do NOT bump major versions of `@fastify/*` packages
- Do NOT auto-format `.sql` fixture files
That last section is the most valuable. Claude Code is aggressive about "helpful" refactors. Explicit boundaries stop it from cleaning up your legacy directory at 2am.
Step 2: Set up the .claude/ directory
Inside your repo, create a .claude/ folder. This is where the interesting stuff lives.
Bash
mkdir -p .claude/commands
mkdir -p .claude/agents
touch .claude/settings.json
Your settings.json controls permissions per-project. A sane default for a product repo:
JSON
{
"permissions": {
"allow": [
"Bash(pnpm test:*)",
"Bash(pnpm typecheck)",
"Bash(pnpm lint:*)",
"Bash(git status)",
"Bash(git diff:*)",
"Bash(git log:*)"
],
"deny": [
"Bash(git push:*)",
"Bash(pnpm publish:*)",
"Bash(rm -rf:*)"
]
}
}
Allowlist the read-only and idempotent commands. Blocklist anything that touches remote state. You'll stop confirming every pnpm test while keeping the guardrails on the scary stuff.
Step 3: Build custom slash commands
This is the underrated superpower. Custom slash commands turn multi-step workflows into single-word invocations.
Create .claude/commands/plan.md:
Markdown
---
description: Turn a spec into a step-by-step implementation plan
---
Read the spec at $ARGUMENTS. Then:
1. Identify the files that will need to change
2. Draft a plan with 4-8 discrete steps
3. Flag any ambiguity in the spec that needs product input
4. Do NOT write code yet — output the plan only
Now /plan specs/checkout-redesign.md runs that exact prompt. No re-typing, no drift between team members.
A few commands worth building on day one:
| Command | What it does |
|---|---|
/plan | Reads a spec, outputs an implementation plan |
/scope | Estimates lines-of-change and blast radius before editing |
/review | Runs a self-review on the current diff before you commit |
/spec-check | Compares finished code back against the original spec |
/db-migration | Generates a Prisma migration with a rollback plan |
And yes, you can commit these to your repo. Which means every engineer on the team is using the same prompts. That consistency is worth more than any single model upgrade.
Step 4: Adopt a spec-first workflow
Claude Code performs dramatically better when it starts from a written spec instead of a Slack message. Anthropic's own engineering guide urges teams to give Claude Code specific, written context up front — vague prompts produce vague plans.
Create a specs/ directory. For each feature, drop a file like:
Markdown
# Spec: Refund flow for annual subscriptions
## Goal
Allow customer support to issue prorated refunds on annual plans without escalating to engineering.
## Non-goals
- Refunds on monthly plans (already handled)
- Partial-month proration logic changes
## Acceptance criteria
- New endpoint POST /admin/refunds/annual
- Requires admin role
- Writes an audit log entry
- Returns 409 if refund window (90 days) has passed
## Out of scope
Any UI work — Design will build the admin panel next sprint.
Then you run /plan specs/annual-refund.md and let Claude produce the plan before touching code. It's honestly the single biggest quality improvement you can make.
Step 5: Split product work across sub-agents
For anything bigger than a small bug fix, run parallel sub-agents. Claude Code's Task primitive lets you spawn scoped workers that share nothing but the initial brief.
Photo by Mushvig Niftaliyev on Unsplash
A typical product feature splits into:
- Research agent — reads existing code, surfaces the relevant files, reports back in under 300 words
- Implementation agent — makes the code changes based on the research
- Test agent — writes and runs the tests
- Review agent — self-critiques the diff before you see it
You don't need to orchestrate this by hand. Prompt Claude Code with "use the research agent to find where refunds are handled today, then plan the implementation" and it'll route correctly.
The main win is context hygiene. Each sub-agent burns its own window on grunt work, so your main conversation stays focused on decisions.
Step 6: Wire in a PR review loop
This is where most teams drop the ball. Claude Code is good at writing code and bad at knowing when it's done. Set up a review command that runs before every commit.
Create .claude/commands/review.md:
Markdown
---
description: Self-review the current diff before commit
---
Run `git diff --staged` and review the changes. Check:
1. Does every changed file match the spec?
2. Are there any TODO comments or console.logs left behind?
3. Did any tests actually run, or were they only compiled?
4. Are error paths covered, or is happy-path only?
5. Is anything imported but unused?
Output a punch list. Do not fix anything yet.
Run /review before every git commit. It catches the top-three most common Claude Code failure modes: dead code, uncovered branches, and tests that pass because they don't actually assert anything.
For teams on GitHub, you can also add Claude's GitHub Action so every PR gets a bot review. Pair it with real human review; don't replace it.
Step 7: Manage context aggressively
Claude Opus 4.6 has a 1M-token context window, but that doesn't mean you should fill it. Long conversations lead to instruction drift, where earlier constraints get forgotten by the time you hit the actual implementation.
A few habits that pay off:
- Use
/clearbetween unrelated tasks. Don't let context bleed across features. - Compact aggressively when the conversation crosses ~50K tokens. Claude Code's
/compactcommand is decent at preserving decisions. - Prefer sub-agents for anything read-heavy so junk data doesn't pollute your main thread.
- Keep
CLAUDE.mdunder 400 lines. Longer files get skimmed, not read.
And don't paste huge log dumps directly. Save them to logs/ and reference the path.
Tips and common pitfalls
A few things you'll learn the hard way if nobody tells you:
The tool loves to "improve" adjacent code. If you ask for a small bug fix, it'll often refactor three unrelated files while it's in there. Add a "don't touch anything outside the specified files" line to your commands and it mostly behaves.
Tests can lie. Claude Code sometimes writes tests that pass because they mock the exact thing they should be testing. Always spot-check test files by reading them, not just running them.
Permissions creep. Every time you approve a Bash command, add it to your allow list if it's safe. Otherwise you're just retraining muscle memory to hit "y" without reading, which is how bad commands sneak through.
Don't share the CLAUDE.md between apps in a monorepo. Each app needs its own scoped context. Root-level CLAUDE.md should be short and delegate to per-app files.
Testing your setup
Before you rely on this workflow for real work, run a smoke test:
- Pick a small, well-scoped bug in your issue tracker
- Write a one-paragraph spec for it in
specs/ - Run
/plan specs/your-bug.md - Review the plan; correct any wrong assumptions
- Have Claude implement it, then run
/review - Open a PR and note where the model tripped up
Do this three times before scaling to your team. You'll uncover which CLAUDE.md sections need tightening and which slash commands need new steps.
Next steps
Once the basics land, layer in:
- Team-shared prompts. Commit
.claude/commands/to your repo so everyone shares them. - Hooks. Wire pre-commit hooks that block commits if
/reviewwasn't run in the last 5 minutes. - Model choice. Use Opus 4.6 for planning, Sonnet 4.6 for the actual code churn. Sonnet 4.6 is roughly 40% cheaper per token ($3/$15 per MTok versus Opus at $5/$25) and comparable to Opus on most day-to-day coding tasks.
- Observability. Log every Claude Code session to a shared folder so you can audit what the agent did and when.
Product work with Claude Code isn't about the model. It's about the scaffolding around it. Get the scaffolding right and you'll ship faster than any team trying to do it raw.
