This article was originally published on aicoderscope.com
Most Claude Code users treat it like a smarter terminal chatbot: type a request, read the output, repeat. That works well enough for one-off tasks. It fails badly for anything that spans more than a single session, involves a non-trivial codebase, or has to fit inside a budget.
The structured setup — CLAUDE.md per project, custom slash commands in .claude/commands/, specialized subagents, and a handful of hooks — is what separates a $200/month Max user who burns through their quota by Wednesday from a $20/month Pro user who ships more code by Friday.
This is that setup, with real numbers and specific file contents.
The chatbot trap
Three habits mark the developer who will regret their Claude Code subscription within a month:
Pasting full files into Chat. You open src/api/handlers/payments.ts, copy 600 lines, paste it with "what's wrong here?" Claude reads it, answers, and now your context window holds 600 lines of boilerplate for every message that follows. Every subsequent turn pays the token cost of those 600 lines. By message 15 you hit "Prompt is too long" and lose the session.
Re-explaining the project every session. "This is a Next.js 14 app with a Prisma ORM backed by PostgreSQL. We use tRPC for the API layer. We deploy to Vercel. Please don't suggest Mongoose..." — typed again, for the fourth week in a row.
Using Opus for everything. Checking if a console.log was removed? That doesn't need Claude Opus 4.7. It needs Claude Haiku 4.5, which costs $1/M input tokens versus Opus's $5/M. Running Opus by default on the kind of work Sonnet handles just as well is the fastest way to burn through a Max 5x subscription.
The fix for all three is structural, not behavioral.
CLAUDE.md per project: the minimal viable setup
CLAUDE.md is the file Claude reads at the start of every session in your project. It acts as the permanent context you used to re-type every time. Claude's docs put it plainly: "Add to it when Claude makes the same mistake a second time." That's the right bar.
Two scoped locations matter:
| Location | Scope |
|---|---|
./CLAUDE.md or ./.claude/CLAUDE.md
|
Project-wide, committed to git, visible to the whole team |
~/.claude/CLAUDE.md |
Personal, applies across all your projects |
./CLAUDE.local.md |
Personal + project-specific, add to .gitignore
|
Keep each file under 200 lines. Longer files consume context tokens on every message and degrade adherence — Claude starts treating them as background noise rather than instructions.
A sample for a TypeScript backend
# Project: payments-api
## Stack
- Node.js 22, TypeScript strict mode
- Prisma 5.x + PostgreSQL 16
- tRPC v11 for API layer
- Vitest for unit tests; supertest for integration tests
- Deployed via Vercel (serverless functions)
## Commands
- `npm run dev` — start local dev server (port 3000)
- `npm run test` — run Vitest
- `npm run typecheck` — tsc --noEmit
- `npx prisma migrate dev` — apply local migration
## Conventions
- Use `zod` for all input validation, not manual if-checks
- Error handling: throw `TRPCError` with appropriate code, never raw `new Error()`
- Database queries live in `src/db/queries/`, never inline in route handlers
- No `any` types. If you can't avoid it, add a `TODO(type):` comment
- All money amounts in integer cents; never floats
## Things Claude should never do
- Suggest switching ORMs
- Use `console.log` for production logging; use `src/lib/logger.ts`
- Add new npm dependencies without asking first
- Run `prisma migrate deploy` (production command — requires explicit confirmation)
That's 25 lines. It removes the top 5 questions Claude would otherwise ask you, and the top 3 mistakes it would otherwise make.
For larger projects, move subsystem rules into .claude/rules/ as separate markdown files. Path-scoped rules load only when Claude opens matching files — your testing.md rules can specify paths: ["**/*.test.ts"] so they appear in context only during test work, not when editing migrations.
Custom slash commands: 3 examples you'll use every day
Slash commands live in .claude/commands/<name>.md (project scope) or ~/.claude/commands/<name>.md (personal scope). The filename is the command name. Type /name in any session to run it.
The modern equivalent is .claude/skills/<name>/SKILL.md, which also supports autonomous invocation — but .claude/commands/ still works and is simpler for custom prompts.
/pr-review — code review before every merge
---
allowed-tools: Read, Grep, Glob, Bash(git diff *), Bash(git log *)
description: Review staged changes before opening a PR
---
## Context
- Changed files: !`git diff --name-only HEAD~1`
- Full diff: !`git diff HEAD~1`
- Recent commits: !`git log --oneline -5`
## Review checklist
1. Check for security issues: SQL injection, XSS, exposed secrets, missing input validation
2. Verify error handling is consistent with the project pattern (TRPCError, not raw throws)
3. Check for missing or incorrect TypeScript types
4. Flag any inline `TODO` comments that should be issues instead
5. Call out any new npm dependencies added without a corresponding package.json note
Provide feedback as a prioritized list: MUST FIX → SHOULD FIX → OPTIONAL.
Use it: /pr-review. Claude runs git diff automatically via the !command syntax and reviews what's actually staged — no copy-pasting.
/test-failure-fix — diagnose a failing test
---
allowed-tools: Bash, Read, Edit
argument-hint: [test-file-path]
description: Run a failing test and fix it
---
Run the failing test at $ARGUMENTS, then diagnose and fix the failure.
Steps:
1. Run: `npx vitest run $ARGUMENTS --reporter=verbose`
2. Read the relevant source file
3. Identify the root cause — distinguish a real bug from a stale test
4. Fix the source (preferred) or update the test if the assertion is genuinely wrong
5. Re-run to confirm the test passes
6. Stop after one fix attempt — don't spiral into refactoring
Use it: /test-failure-fix src/api/payments.test.ts. One focused command instead of a multi-turn conversation.
/deploy — pre-deployment checklist
---
allowed-tools: Bash, Read
description: Run pre-deployment checks before pushing
---
Run the full pre-deployment checklist:
1. `npm run typecheck` — must pass with zero errors
2. `npm run test` — all tests must pass
3. `git diff --stat origin/main` — show what's shipping
4. Check for any `console.log` calls added recently: !`git diff origin/main | grep "console.log"`
5. Check for any hardcoded secrets or API keys: !`git diff origin/main | grep -i "secret\|api_key\|password" | grep "^+" | grep -v "// "`
If all checks pass, print "✓ Ready to deploy." If any fail, print the specific error and stop.
Use it: /deploy. Three minutes saved per deployment, every deployment.
Subagents for specialized work
A subagent is a separate Claude instance that runs a focused task and returns only its final answer to the parent conversation. The key benefit isn't intelligence — it's context isolation. The subagent can read 40 files, run tests, and generate a long analysis without any of that intermediate noise accumulating in your main session.
Define subagents as files in .claude/agents/<name>.md:
Code-reviewer subagent
markdown
---
name: code-reviewer
description: Expert security and quality reviewer. Invoke when reviewing a PR, new module, or any code with auth/payment logic.
model: sonnet
tools: [Read, Grep, Glob]
---
You are a code review specialist focused on security, correctness, and maintainability.
When reviewing code:
- Identify injection risks, privilege escalation paths, and missing input validation
- Flag type safety gaps and incorrect error propagation
- Check for missing tests on critical paths
- Suggest specific fixes with line references, not general advice
Return a structured report: Critical → High → Medium →
Top comments (0)