claude-scaffold

Stop fighting your AI agent — give it the right project structure.

A production-ready project scaffold for Claude Code agents. Drop these files into any repo and Claude instantly understands your architecture, conventions, and task flow.

Why this exists

Claude Code is powerful, but without structure it:

• Asks the same questions every conversation
• Ignores your conventions after context window rotates
• Writes code that doesn't match your patterns
• Can't prioritize or track complex multi-step work

claude-scaffold solves this with a minimal file structure that gives Claude persistent, actionable context.

Quick start

Option A: Fork and customize

# Fork this repo, then:
git clone https://github.com/YOUR_USERNAME/claude-scaffold.git my-project
cd my-project
# Edit CLAUDE.md and .agents/ files for your project

Option B: Copy into existing project

# From your project root:
curl -sL https://github.com/gkosach/claude-scaffold/archive/main.tar.gz | tar xz --strip=1 -C .
# Edit CLAUDE.md and .agents/ files for your project

Option C: Manual setup

Copy these files into your project root:

CLAUDE.md
.agents/
  EXAMPLE.md
  CONVENTIONS.md
  TESTING.md
docs/
  TASKS.md

Then customize each file. Every file has TODO: markers where you fill in your project details.

File structure

your-project/
  CLAUDE.md               # Entry point. Claude reads this FIRST every conversation.
  |                        # Project overview + agent rules + pointers to .agents/
  |
  .agents/                 # Domain context files. Claude reads these based on task.
  |  EXAMPLE.md            # Template: copy & rename per domain area
  |  CONVENTIONS.md        # Runtime code rules: error handling, async, DB, types
  |  TESTING.md            # Test philosophy & patterns (read when writing tests)
  |
  docs/
     TASKS.md              # Jira-style task breakdown with dependencies & blockers

How it works

1. CLAUDE.md — the entry point

Claude Code automatically reads CLAUDE.md at the start of every conversation. This file should contain:

• Project identity: what this is, what stack it uses (2-3 lines)
• Agent rules: how Claude should behave in THIS project
• Pointers: where to find deeper context (.agents/, docs/)

# Project: my-app

E-commerce platform. Next.js 14, tRPC, Prisma, PostgreSQL, Redis.

# Rules for AI agents:

- use English for code and comments
- follow existing patterns, don't invent new ones
- ...

## Next steps
- .agents/ — domain context per area
- docs/TASKS.md — current task breakdown

Keep it under 100 lines. Claude reads this every time — make it count.

2. .agents/ — domain context

Each file describes one area of your system. Claude reads the relevant file based on the task at hand. This is where you put the details that would be too much for CLAUDE.md.

Name files by domain, not by role:

• BACKEND.md — API layer, DB patterns, auth
• FRONTEND.md — component structure, state management
• INFRASTRUCTURE.md — deployment, Docker, env vars
• CONVENTIONS.md — code style rules Claude must follow
• TESTING.md — test patterns and anti-patterns

Good .agents/ file = things Claude can't derive from reading code:

• WHY you chose this pattern (not just what the pattern is)
• Traps and gotchas specific to your codebase
• Cross-cutting concerns (auth flow, error hierarchy, data flow)
• Performance constraints and SLAs

3. docs/TASKS.md — task management

Jira-style task breakdown that Claude can read and track:

• Epics and tasks with IDs (INFRA-001, AUTH-002)
• Dependencies and blockers (blocked by: INFRA-001)
• Priority levels ([P0] critical path, [P1] high, [P2] medium)
• Phases with clear ordering

This prevents Claude from trying to do everything at once and gives it a roadmap.

Best practices

Do

• Be specific: "use pino for logging, JSON format, correlation IDs" > "use structured logging"
• Explain WHY: "no ORMs — we need raw SQL for ClickHouse MergeTree optimizations" > "don't use ORMs"
• Include examples: one code snippet is worth 50 words of explanation
• Update regularly: stale context is worse than no context
• Keep CLAUDE.md short: it's read every conversation, so every line must earn its place

Don't

• Don't duplicate code: conventions should describe patterns, not copy-paste implementation
• Don't describe file contents: Claude can read files — describe what's NOT obvious from reading
• Don't over-constrain: rules like "never use ternary operators" waste context on style preferences your linter handles
• Don't put secrets: these files are committed to git

Real-world example

See the headless project for a full real-world implementation:

• Complex multi-service architecture (Orchestrator, Browser Pool, Data Pipeline)
• 41 tasks across 8 phases with dependency graph
• Domain-specific agent files (BROWSER.md, DATA.md, INFRASTRUCTURE.md)
• Comprehensive code conventions

Compatibility

Works with:

• Claude Code CLI — reads CLAUDE.md automatically
• Claude Code in VS Code / JetBrains — same behavior
• Any AI agent that supports project-level context files

The .agents/ pattern is a convention, not a framework. No dependencies, no tooling, no lock-in.

Contributing

PRs welcome. If you've found patterns that make Claude more effective, share them.

License

MIT — use it everywhere, fork it freely.