Skip to content

best-practices.md

Latest commit

 

History

History
324 lines (249 loc) · 10.3 KB

best-practices.md

File metadata and controls

324 lines (249 loc) · 10.3 KB

Best Practices for AI Coding Agents

Principles that make AI agents (Claude Code, Codex, Cursor, Aider, etc.) work better on your projects.

📚 Related Guides

Guide Topics Covered
Pre-Commit Build Gate The single highest-leverage hook for any repo
AGENTS.md Contract Stable entrypoint pointer for tool-portable repos
MCP Optimization CLI vs MCP, token costs, config switching
Doc Organization Clean root, docs/ structure, naming conventions
Audit Your Project Run an agent audit, scorecard, recommendations
Engineering Principles Core principles for AI-first development
Patterns Fresh context, file-based state, handoffs
Web Design Principles Building sites with AI agents

CLAUDE.md Setup

Every project needs a CLAUDE.md file in the root. This is the agent's instruction manual.

Keep It Short

  • Target: < 100 lines (ideally 60)
  • Agents read this every session
  • Long files waste context tokens
  • If it's over 100 lines, split into linked docs

Use Lookup Tables

Instead of prose, use tables. Agents parse these efficiently:

## Lookup Table
| Concept | Files | Search Terms |
|---------|-------|--------------|
| Auth | src/auth/, src/middleware/auth.ts | login, JWT, session |
| API | src/routes/api/ | endpoint, handler, POST |
| Database | prisma/schema.prisma, src/db/ | query, model, migration |
| Testing | __tests__/, src/**/*.test.ts | vitest, mock, expect |
| Config | src/config/, .env.example | environment, settings |

Why this works:

  • Agent knows exactly where to look
  • Reduces searching/guessing
  • Search terms help find related code

Include Commands

## Commands
```bash
npm run build    # Build (must pass before commit)
npm test         # Run tests
npm run lint     # Check code style

### State Current Focus
```markdown
## Current Focus
Building user dashboard - see specs/dashboard.md

⚠️ No Content Loss When Trimming CLAUDE.md

Every section removed from CLAUDE.md must survive in a linked doc. New agent sessions only see CLAUDE.md automatically — if content isn't linked, it's lost.

When trimming CLAUDE.md to < 100 lines:

  1. Identify every section being removed (roadmap tables, file maps, brand guide, etc.)
  2. Verify each has a home in docs/, specs/, or another tracked file
  3. If no home exists, create one (e.g., docs/brand.md, docs/architecture.md)
  4. Link from CLAUDE.md via the lookup table or a direct reference
  5. Link from docs/README.md so the master index stays complete

The lookup table in CLAUDE.md is the bridge — it tells future sessions where to find everything that was trimmed out.

Context Window Basics

Claude has a 200K token context window, but you don't get all of it. Understanding the real budget prevents agent degradation mid-task.

The Real Budget

TOTAL: ~176K usable tokens (not 200K)

Fixed overhead:
- Model/harness overhead:  ~32K
- CLAUDE.md:                ~2K
- MCP servers:             0-50K (varies by config!)
─────────────────────────────
Available for work:        92-142K

MCP servers are the biggest variable. Each server injects tool definitions into context. If you have 5+ MCP servers enabled, you may be burning 40-50K tokens before the agent reads a single file. Use CLI > MCP when possible (see MCP Optimization).

Warning Thresholds

Token Usage Status Action
0-50K 🟢 Safe Work normally
50-100K 🟡 Monitor Keep tasks focused
100-150K 🟠 Wrap up Finish current task, don't start new ones
150K+ 🔴 Reset Agent quality degrades — start fresh context

Why This Matters for Overnight Runs

  • Each worker gets a fresh context (good)
  • But if a single task is too large, the agent hits 150K+ and starts producing lower quality output
  • Keep tasks to 5-15 minutes of focused work to stay in the green/yellow zone
  • If an agent's output looks sloppy or repetitive, the task was probably too big

The 10 Principles

1. One Task = One Context

  • Each agent session should do ONE thing
  • 5-15 minutes of focused work
  • Don't ask for "build the whole feature"
  • Break it into specific tasks

2. Fresh Context Every Time

  • Agents don't remember previous sessions
  • Each worker starts clean
  • Write handoffs so next worker has context
  • Don't rely on "we discussed this earlier"

3. Specific Tasks Get Specific Results

Bad:

- [ ] Add authentication

Good:

- [ ] Create login form component at src/components/LoginForm.tsx with email/password fields
- [ ] Add POST /api/auth/login endpoint that validates credentials and returns JWT
- [ ] Write tests for LoginForm component (test validation, submission, error states)

4. Include Acceptance Criteria

- [ ] Add user profile page - DONE when: page loads user data, shows avatar, edit button works, tests pass

5. Order Tasks by Dependency

Put setup tasks before tasks that depend on them:

- [ ] Create database schema for users table
- [ ] Add User model with TypeScript types
- [ ] Create API endpoint to fetch user
- [ ] Build UI component to display user

6. Tests = Quality Gate

  • Include "run tests" or "verify build passes" in tasks
  • Agents should not mark complete if tests fail
  • Tests catch mistakes before you wake up

7. Git is Your Safety Net

  • Agents commit their work
  • Review commits in the morning
  • git diff shows exactly what changed
  • git revert if something went wrong

8. Delegate, Don't Micromanage

Micromanaging (bad):

- [ ] Create function called validateEmail that takes string parameter email and uses regex /^[^\s@]+@[^\s@]+\.[^\s@]+$/ to return boolean

Delegating (good):

- [ ] Add email validation to the signup form. Follow existing validation patterns in the codebase.

9. Working Code Only

  • Agents should commit code that runs
  • No placeholder comments like "// TODO: implement this"
  • If it can't be fully done, note what's missing

10. Review the Handoffs

  • Check the agent's run logs / handoff files
  • See what the agent did and struggled with
  • Use this to write better tasks next time

.claudeignore

Add a .claudeignore file to your project root. This tells Claude which files to skip when searching your codebase. Without it, agents waste tokens reading files they can't use and may hit "Request too large" errors.

# .claudeignore

# Binary files (Claude can't read these, wastes tokens trying)
**/*.pdf
**/*.docx
**/*.xlsx
**/*.pptx

# Dependencies (massive, never useful)
node_modules/
.next/
dist/
build/
__pycache__/
*.pyc
.venv/
venv/

# Archives (old docs that pollute search results)
ARCHIVE/
docs/historical/

# Large generated files
*.min.js
*.min.css
package-lock.json
yarn.lock

Why this matters:

  • PDFs cause "Request too large" errors that kill agent sessions
  • node_modules/ has thousands of files that slow down searches
  • Old archived docs surface stale information during agent searches
  • Every file Claude reads costs context tokens

Pro tip: If your project has PDFs the agent needs, convert them to markdown first and reference the .md version.

Project Structure That Works

Agents work best with organized projects:

your-project/
├── CLAUDE.md              # Agent instructions (required)
├── .claudeignore          # Files to skip (recommended)
├── src/
│   ├── components/        # UI components
│   ├── routes/            # API routes
│   ├── services/          # Business logic
│   └── utils/             # Helpers
├── tests/                 # Test files
├── docs/                  # Documentation
│   └── specs/             # Feature specifications
├── package.json           # Dependencies & scripts
└── tsconfig.json          # TypeScript config

Key points:

  • Feature-based organization (not type-based)
  • Consistent naming conventions
  • Tests next to or mirroring source structure
  • Specs in docs/ for complex features

Common Mistakes

Too Many Tasks at Once

❌ 50 tasks in TASKS.md ✅ 5-10 focused tasks per overnight run

Vague Tasks

❌ "Improve the UI" ✅ "Add loading spinner to submit button in LoginForm.tsx"

No CLAUDE.md

❌ Agent guesses about project structure ✅ Agent knows exactly where things are

Ignoring Handoffs

❌ Never read what the agent wrote ✅ Review handoffs, learn, improve tasks

No Tests

❌ Agent makes changes, no verification ✅ Tests catch issues automatically

No .claudeignore

❌ Agent chokes on PDFs, wastes tokens searching node_modules ✅ Agent only searches relevant source files

Quick Checklist

Before running overnight:

  • CLAUDE.md exists and is < 100 lines
  • .claudeignore excludes PDFs, node_modules, and archives
  • Lookup table maps concepts to files
  • Build/test commands are documented
  • Tasks are specific with acceptance criteria
  • Tasks are ordered by dependency
  • Git repo is clean (commit current work)
  • Tests exist and pass currently

Learn More

Free Resources:

Go Deeper:

Community: