CLAUDE.md Mastery: The Spec File That Turns AI Coding Agents from Chatbots into Team Members

Every AI coding agent starts your session with a blank slate. It does not know you use PostgreSQL, not SQLite. It does not know your team prefixes React components with Modern. It does not know your backend lives in src/ and your mobile app in mobile/src/. It does not know that you never write raw SQL, always use Prisma. It does not know the 40 conventions your team has accumulated over three years.

So it guesses. And it guesses wrong — not catastrophically, but consistently enough to create friction. You correct it. It apologizes, fixes it, and forgets again by the next session.

The fix is not a better model. It is a spec file.

CLAUDE.md (for Claude Code), AGENTS.md (the emerging open convention for all agents), and .cursor/rules (for Cursor) are plain-text files you drop into your project that give AI agents persistent, session-proof knowledge of your codebase. They are the difference between an AI that onboards once and an AI you have to re-onboard every session.

This is the practical guide to writing ones that actually work.

The Third Era Problem

Cursor's CEO Michael Truell framed it well: we are in the third era of AI software development. Era one was autocomplete — AI that finished your line. Era two was chat — AI you explained things to. Era three is autonomous agents — AI that opens files, runs commands, writes tests, and opens PRs while you sleep.

The era-three problem is that autonomous agents need context the same way a new hire does. A new hire on day one does not know your deployment process, your naming conventions, your non-obvious architectural decisions. You do not explain them from scratch in every meeting. You write them in an onboarding doc.

Spec files are the onboarding doc for your AI agents.

CLAUDE.md: Four Tiers of Scope

Claude Code's memory system supports four distinct file locations, each with a different scope. Understanding the hierarchy is what lets you apply rules precisely without polluting every project with global noise.

More specific scopes override broader ones. A project-level rule that says "use pnpm" overrides a user-level rule that says "use npm."

For teams, the managed policy tier is underused. IT and DevOps can push org-wide guardrails — never commit credentials, always run tests before push, never use eval() — that apply to every developer's Claude Code session without them having to think about it.

The Anatomy of a Great Spec File

A spec file that actually changes agent behavior has five sections. Most spec files people write have one (usually just "use TypeScript"). The other four are where the leverage is.

1. Stack Declaration

What technologies does this project use? Be specific. Do not write "React Native" — write the exact version and any significant configuration choices that affect code generation.

## Stack
- **Mobile**: React Native 0.80.2 + TypeScript, Expo is NOT used
- **Backend**: Node.js + Fastify + Prisma ORM (PostgreSQL)
- **Auth**: JWT with refresh tokens, stored in SecureStore on mobile
- **API client**: Axios instance at `mobile/src/config/api.ts`
- **Navigation**: React Navigation v7, file-based tab + stack pattern
- **Styling**: StyleSheet API only — no styled-components, no Tailwind

2. Conventions and Anti-Patterns

This is where most of the value lives. Document what your team has learned the hard way.

## Conventions
- Components are prefixed: `Modern` (consumer), `Provider` (provider), no prefix (admin)
- All API calls go through the `api` Axios instance — never use `fetch` directly
- Theme colors always via `theme.colors.*` — never hardcode hex values
- Status strings: `CONFIRMED`, `CANCELLED_BY_CONSUMER`, `CANCELLED_BY_PROVIDER` (not `CANCELLED`)
- Hooks must always be declared before any conditional returns (Rules of Hooks)
 
## Never do this
- Never add `|| true` to boolean values — use `?? false` or `?? true`
- Never use `Alert.prompt` — it is iOS-only, use a Modal + TextInput instead
- Never use `console.log` in production — remove or wrap in `if (__DEV__)`
- Never fall back to hardcoded mock data — show an empty state instead

3. Architecture Map

AI agents explore codebases by reading files. An architecture map tells them where things live so they stop guessing.

## Architecture
- **Mobile screens**: `mobile/src/screens/{consumer,provider,admin,booking,profile,analytics}/`
- **Backend routes**: `src/routes/` — each file is one domain (auth, booking, service, provider)
- **Backend controllers**: `src/controllers/` — business logic, called by routes
- **Services**: `src/services/` — DB queries, external APIs, never called directly from routes
- **Theme**: `mobile/src/contexts/ThemeContext.tsx` — always use `useTheme()` hook

4. Workflow and Commands

Build commands, test commands, and deployment notes that agents need to actually run things.

## Commands
- Install: `cd mobile && yarn install`
- Backend: `npm run dev` (from root) — runs on port 3001
- Mobile: `cd mobile && npx react-native run-android` or `run-ios`
- Lint: `cd mobile && npx eslint src --ext .ts,.tsx`
- Database: `npx prisma db push` (schema changes), `npx prisma db seed` (seed data)
 
## Before committing
- Run lint and fix all errors
- Never commit directly to `main` — always use a branch and PR

5. Output Behavior Rules

This is the section the Universal CLAUDE.md project showed can cut output verbosity by 63%. Default Claude behavior — opening with "Sure!", restating your question, adding unsolicited suggestions — is not wrong, but it is expensive and noisy in automation contexts.

## Response style
- Skip preamble. No "Sure!", "Great question!", "Absolutely!" openers
- Do not restate the question before answering
- No closing "Let me know if you need anything!" — just end the response
- When asked to fix a bug, fix exactly that bug — do not add unrequested improvements
- Code changes should be minimal and surgical — prefer editing existing patterns over introducing new abstractions

Cursor Rules: The Same Concept, Different Format

Cursor's equivalent is .cursor/rules/ — a directory where each .mdc file is a scoped rule set. The key addition Cursor brings is file-pattern scoping: you can write rules that only apply when the agent is editing TypeScript files, or only React components, or only test files.

.cursor/
  rules/
    typescript.mdc       # TypeScript-specific rules
    react-native.mdc     # RN component patterns
    api-routes.mdc       # Backend route conventions
    tests.mdc            # Testing standards

Each .mdc file can declare which file patterns it applies to:

---
globs: "mobile/src/screens/**/*.tsx"
---
 
## Screen conventions
- Every screen must use `useTheme()` and `theme.colors.*` for all colors
- No hardcoded hex values in StyleSheet
- Hooks always declared before any conditional returns
- Empty states required for all list views (ListEmptyComponent)

This specificity is the advantage over a monolithic CLAUDE.md. A rule about test file naming only fires when the agent is writing tests. It doesn't consume tokens when it's writing migration scripts.

Multi-Agent Spec Inheritance

Where spec files become genuinely powerful is in multi-agent workflows. When you fan out work to parallel agents — one fixing authentication bugs, another optimizing database queries, a third writing tests — they all start from the same conventions because they all read the same CLAUDE.md.

## For automated agents
- Branch naming: `fix/issue-{number}` or `feat/description`
- PR target: always `main`
- Commit format: `fix: description\n\nFixes #{number}`
- Max ~30 lines changed per file — prefer surgical edits
- Do not introduce new dependencies without explicit instruction
- Do not modify files outside the scope of the task

The "max 30 lines per file" rule is particularly useful. Without it, agents given latitude will sometimes rewrite entire screens when asked to fix a single bug. One explicit constraint eliminates the entire class of "the agent went off-scope" problems.

What Spec Files Eliminate

What Spec Files Open Up

Truly autonomous agents. When a sub-agent knows your conventions, file locations, commands, and output format, you can assign it a bug to fix and trust the output. Without a spec file, automation requires human review of every output; with one, you can set a higher bar before pulling humans in.

Faster real human onboarding. A well-written CLAUDE.md is also the best onboarding doc you have ever written for actual new engineers. The discipline of writing it for AI forces the clarity that prose onboarding docs lack.

Org-wide standards enforcement. The managed policy tier means your security team can push a CLAUDE.md to every developer's machine that bans known-dangerous patterns — eval(), hardcoded credentials, raw SQL — and it applies everywhere, automatically, without code reviews or linters.

Solo founders operating like teams. A single developer with a well-tuned spec file and a multi-agent workflow can maintain a codebase that would normally require three or four people — not because AI is magic, but because the spec file eliminates the overhead that makes scale hard.

A Practical Starting Template

# Project: {Your Project Name}
 
## Stack
- Language: TypeScript
- Framework: {Next.js / React Native / Express / etc.}
- Database: {PostgreSQL / SQLite / etc.} via {Prisma / Drizzle / raw}
- Testing: {Jest / Vitest / Playwright}
 
## Conventions
- {Name your most important convention}
- {Name a pattern your team uses that's non-obvious}
- {Name something AI consistently gets wrong}
 
## Never do this
- {Anti-pattern 1}
- {Anti-pattern 2}
 
## Architecture
- {Key directories and what lives where}
- {Any non-standard patterns}
 
## Commands
- Install: 
- Dev server: 
- Test: 
- Lint: 
 
## Response style
- Skip preamble — no "Sure!" or "Great question!"
- Surgical edits only — do not refactor beyond the scope of the task
- No console.log in commits

Start with the "never do this" section. It is usually the highest-leverage section because it targets the specific AI behaviors that are already frustrating you. Everything else you can fill in as you notice gaps.

The companion templates for this article — a full CLAUDE.md generator script, a multi-project AGENTS.md template, and a spec file linter — are at github.com/aistackinsights/stackinsights.

Sources & Further Reading

1. Claude Code Memory — Official Documentation. Anthropic, 2026
2. Universal CLAUDE.md — Cut output tokens by 63%. GitHub, 2026
3. Truell, M. (2026). The Third Era of AI Software Development. Cursor Blog
4. Robinson, L. (2026). Best Practices for Coding with Agents. Cursor Blog
5. McPeak, T. (2026). Securing Our Codebase with Autonomous Agents. Cursor Blog
6. Build Agents That Run Automatically. Cursor Blog, 2026
7. Cursor Rules Documentation. Cursor, 2026
8. Anthropic Engineering. (2024). Building Effective Agents
9. GitHub Copilot Custom Instructions. GitHub Docs, 2026
10. OpenAI Codex AGENTS.md Convention. OpenAI, 2026
11. Windsurf Rules and Memories. Codeium, 2026
12. Claude Code Sub-Agents. Anthropic, 2026