Using Documentation as Effective AI Context

You just onboarded a new developer. They spend their first week asking the same questions: “How do I run the tests?” “What’s the deployment process?” “Why do we use this pattern instead of that one?” Now imagine that developer asks those same questions every single morning because they forget overnight.

That is what working with an AI coding assistant feels like without documentation-as-context. Every new session, the AI starts from zero. It does not know your build commands, your team’s conventions, or your architectural decisions. It rediscovers them by reading files — burning context tokens on information you could have told it in 10 lines.

What You’ll Walk Away With

• A template for each tool’s configuration file (CLAUDE.md, .cursor/rules, AGENTS.md)
• Guidelines for what to include and what to leave out
• Prompts for bootstrapping documentation from an existing codebase
• A strategy for keeping documentation current as the project evolves

The Three Instruction Systems

Each tool has its own mechanism for persistent, session-level documentation. Despite different names, they serve the same purpose: giving the AI project-specific knowledge it cannot infer from code alone.

Cursor

Project Rules live in .cursor/rules/ as markdown files. They can be scoped by file pattern, applied always, or invoked manually.

.cursor/rules/
  code-style.md          # Always applied
  testing.mdc            # Applied to test files (via globs)
  api-conventions.md     # Agent-decided based on relevance
  deployment.md          # Manual invocation only

Cursor also supports User Rules (global preferences in Cursor Settings) and AGENTS.md as a simpler alternative to .cursor/rules.

Key capabilities:

• Glob-scoped rules: Apply only when working with matching files
• Agent-decided rules: Applied when Cursor determines they are relevant
• Team Rules: Organization-wide rules managed from the dashboard (Team/Enterprise plans)
• Remote rules: Import rules from GitHub repositories that stay synced

Claude Code

CLAUDE.md files are the primary instruction mechanism. Claude reads them at the start of every session.

project/
  CLAUDE.md              # Team-shared project instructions
  CLAUDE.local.md        # Your personal preferences (gitignored)
  .claude/
    CLAUDE.md            # Alternative location
    rules/
      code-style.md      # Modular rules
      testing.md         # Topic-specific guidelines
      api/
        conventions.md   # Path-specific rules

Key capabilities:

• Hierarchical loading: CLAUDE.md in parent directories loads automatically
• Path-specific rules: Use YAML frontmatter with paths field for conditional rules
• Imports: Reference other files with @path/to/file syntax
• Auto memory: Claude writes its own notes to ~/.claude/projects/<project>/memory/
• User-level rules: ~/.claude/CLAUDE.md applies to all projects

Codex

AGENTS.md files provide instructions at global and project levels. Codex reads them at the start of every session.

~/.codex/
  AGENTS.md              # Global defaults for all repos
  AGENTS.override.md     # Temporary global override

project/
  AGENTS.md              # Project-level instructions
  services/
    payments/
      AGENTS.override.md # Service-specific overrides

Key capabilities:

• Precedence chain: Global, then root, then nested — closer files override earlier ones
• Override files: AGENTS.override.md takes priority over AGENTS.md in the same directory
• Fallback filenames: Configure custom instruction file names (e.g., TEAM_GUIDE.md)
• Size limit: 32 KiB by default, configurable via project_doc_max_bytes

What to Include

The golden rule: if removing this line would cause the AI to make a mistake, keep it. If the AI already does this correctly without the line, delete it.

Always Include

Category	Example
Build commands	npm run build, make test, docker compose up
Test commands	npm test -- --testPathPattern=auth, pytest -x
Code style rules that differ from defaults	”Use single quotes”, “2-space indentation”
Architectural patterns	”Repository pattern for data access”, “All API routes in src/pages/api/“
Non-obvious constraints	”Redis must be running for integration tests”, “Use pnpm, not npm”
Environment setup	”Run cp .env.example .env before first build”

Never Include

Category	Why
Standard language conventions	The AI already knows them
File-by-file descriptions	The AI can read the files
Long tutorials or explanations	Too much text causes the AI to ignore important rules
Information that changes frequently	It will become stale and mislead the AI
Self-evident practices	”Write clean code” adds nothing

Copy-paste prompt: Bootstrap documentation from an existing codebase

Analyze this project and generate a [CLAUDE.md / .cursor/rules / AGENTS.md] file.

Include:
1. Build, test, and lint commands (try running them to verify they work)
2. Key architectural patterns you observe
3. Code style conventions that differ from language defaults
4. Important file locations and their purposes
5. Any non-obvious setup requirements

Keep it under 50 lines. Every line should contain information you could NOT
figure out by just reading the code. Prioritize commands and constraints
over descriptions.

Writing Effective Rules

The difference between documentation that works and documentation the AI ignores comes down to specificity and brevity.

Bad: Vague and Verbose

# Code Quality
We care deeply about code quality. Always write clean, maintainable,
well-documented code that follows best practices. Make sure to handle
errors properly and write tests for your code.

Good: Specific and Actionable

# Code Style
- Use ES modules (import/export), not CommonJS (require)
- Prefer async/await over .then() chains
- Error responses: { error: string, code: number } shape

# Testing
- Run single tests with: npm test -- --testPathPattern=<name>
- Never mock the database in integration tests
- Test file location: src/**/__tests__/<name>.test.ts

# Workflow
- Run npm run type-check after making code changes
- NEVER commit to main directly. Always create a branch.

Cursor

Split rules into focused files. Use frontmatter to control when they apply:

---
description: "API endpoint conventions"
globs:
  - "src/api/**/*.ts"
  - "src/routes/**/*.ts"
---

# API Conventions
- All endpoints return { data: T } on success, { error: string } on failure
- Use Zod for request validation
- Include rate limiting middleware on all public endpoints
- Reference @src/api/users.ts as the canonical example

Claude Code

Keep your root CLAUDE.md concise. Use imports for detailed docs:

# Project: Acme API
See @README.md for project overview.
See @package.json for available commands.

# Commands
- Build: npm run build
- Test: npm test -- --testPathPattern=<name>
- Lint: npm run lint

# Conventions
- TypeScript strict mode, no @ts-ignore
- All API routes in src/pages/api/
- Database queries use Drizzle ORM (see @src/lib/db/schema.ts)

Use .claude/rules/ for modular, topic-specific rules. Path-specific rules use YAML frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# API Rules
- Validate all input with Zod schemas
- Return consistent error shapes

Codex

Keep AGENTS.md focused on the most critical information:

# Acme API

## Commands
- Build: npm run build
- Test: npm test -- --testPathPattern=<name>
- Lint: npm run lint

## Working Agreements
- Always run tests after modifying code
- Use pnpm for dependency management
- TypeScript strict mode, no any types
- API routes follow RESTful conventions in src/routes/

Use nested AGENTS.md for service-specific overrides that should not apply globally.

Copy-paste prompt: Audit and improve existing documentation

Read our [CLAUDE.md / .cursor/rules / AGENTS.md] files. Evaluate them:

1. Are there any rules the AI would follow correctly without being told?
   (Remove these -- they waste context)
2. Are there any rules that are too vague to be actionable?
   (Make them specific)
3. What important commands or conventions are MISSING?
   (Add them based on package.json, Makefile, etc.)
4. Is the file too long? (Target under 50 lines for the main file)

Show me the improved version with your changes explained.

Keeping Documentation Current

Documentation that falls out of date is worse than no documentation — it actively misleads the AI.

1. Review monthly. Schedule a 10-minute review of your instruction files. Remove rules that no longer apply. Add rules for mistakes the AI keeps making.
2. Treat it like code. Check instruction files into git. Review changes in PRs. Let the team contribute.
3. Use the AI to maintain it. After a difficult debugging session, ask the AI to add a rule preventing the same issue next time.
4. Watch for ignored rules. If the AI keeps violating a rule, the file is probably too long and the rule is getting lost. Prune aggressively.

Copy-paste prompt: Add a lesson to project documentation

We just discovered that [DESCRIBE THE ISSUE]. Add a rule to our
[CLAUDE.md / .cursor/rules / AGENTS.md] to prevent this in the future.

The rule should be:
- One or two sentences maximum
- Specific and actionable (not "be careful with X")
- Placed in the most relevant section of the file

When This Breaks

The file is too long and rules get ignored. This is the most common failure. Keep your main instruction file under 50 lines. Move detailed guidelines to topic-specific files (.claude/rules/, scoped .cursor/rules/). Use emphasis (“IMPORTANT:”, “YOU MUST”) for critical rules, but sparingly — if everything is important, nothing is.

Different team members add contradictory rules. Treat instruction files like code: review changes, resolve conflicts, keep one source of truth. In Claude Code, use the root CLAUDE.md for team-shared rules and CLAUDE.local.md for personal preferences.

The AI follows outdated rules. If your testing framework changed but your instruction file still references the old one, the AI will use the wrong commands and get confused. Audit regularly.

Too many rules files in a monorepo. With nested instruction files across packages, the combined context can exceed limits. In Codex, the project_doc_max_bytes setting (32 KiB default) caps the total. In Claude Code, only the first 200 lines of auto-memory MEMORY.md are loaded. Keep each file focused.

What’s Next

Memory Patterns Go beyond static files with auto-memory, learned patterns, and cross-session knowledge.

Codebase Indexing How search and indexing complement documentation for finding relevant code.

File Organization Structure your project so the AI can navigate with minimal documentation.