Skip to content
Developer Toolkit

Using Documentation as Effective AI Context

Documentation as context means encoding project-specific knowledge — build commands, code style, architectural decisions — into files like CLAUDE.md, .cursor/rules, and AGENTS.md that the AI reads automatically at the start of every session, instead of rediscovering it by reading code. Effective versions stay specific, brief, and current, since a bloated or stale file gets ignored or actively misleads the assistant.

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 from documentation as context

Section titled “What you’ll walk away with from documentation as context”
  • 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

Section titled “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.

Project Rules live in .cursor/rules/ as markdown files. They can be scoped by file pattern, applied always, or invoked manually. Cursor supports both .md (plain, always-applied text) and .mdc (carries frontmatter for description, globs, and alwaysApply). Only .mdc files honor that metadata — in a plain .md rule the frontmatter is ignored and the file is applied as-is.

.cursor/rules/
  code-style.mdc         # alwaysApply: true in frontmatter
  testing.mdc            # Applied to test files (via globs)
  api-conventions.mdc    # Agent-decided (via description)
  deployment.md          # Plain rule, @-mention to invoke manually

Cursor also supports User Rules (global preferences in Cursor Settings) and AGENTS.md as a simpler alternative to .cursor/rules. Cursor reads AGENTS.md natively in the project root and in any subdirectory, applying it automatically when you work with files in that directory or its children.

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

What to Include

Section titled “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

Section titled “Always Include”
CategoryExample
Build commandsnpm run build, make test, docker compose up
Test commandsnpm 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

Section titled “Never Include”
CategoryWhy
Standard language conventionsThe AI already knows them
File-by-file descriptionsThe AI can read the files
Long tutorials or explanationsToo much text causes the AI to ignore important rules
Information that changes frequentlyIt will become stale and mislead the AI
Self-evident practices”Write clean code” adds nothing

Writing Effective Rules

Section titled “Writing Effective Rules”

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

Bad: Vague and Verbose

Section titled “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

Section titled “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.

Split rules into focused files. To control when a rule applies via description or globs, the file must use the .mdc extension (e.g. api-conventions.mdc) — frontmatter in a plain .md rule is ignored:

---
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

Keeping Documentation Current

Section titled “Keeping Documentation Current”

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

  1. Review monthly, and re-review whenever you change models. The model switch is the trigger that actually matters — a stronger model needs less scaffolding than the one you wrote the file for, and a cheaper one needs more.
  2. Treat it like code. Check instruction files into git. Review changes in PRs. Let the team contribute.
  3. Add a rule only after the same mistake happens twice. After a difficult debugging session it is tempting to ask the AI to write a rule immediately, but a single failure is noise. Every line is read on every turn forever, so a speculative rule costs you permanently for a problem you may not have.
  4. Delete more than you add. Prune on a schedule rather than only when something breaks. Anthropic’s own context engineering post for the Claude 5 generation describes removing over 80% of Claude Code’s system prompt with no measurable loss, and members of the team have been reported as recommending you periodically delete your instruction files entirely and add back only what demonstrably breaks. Treat that stronger version as a reported recommendation rather than documented policy — the official docs still frame it as adding a rule after the same mistake happens twice. Pruning CLAUDE.md and AGENTS.md walks through the full protocol either way.
  5. 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.

When documentation as context breaks down

Section titled “When documentation as context breaks down”

The file is too long and rules get ignored. This is the most common failure, and the fix is counterintuitive: shorten the file, do not add emphasis. Rewriting the rule in bold with “IMPORTANT” in front of it is the instinctive move and it rarely works, because adding instructions degrades adherence to all of them, not just the new ones. The actual fix is usually to delete four other rules. Move detailed guidelines to topic-specific files (.claude/rules/ with a paths glob, scoped .cursor/rules/), and if a rule genuinely must be obeyed rather than considered, make it a hook instead of a sentence.

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, project_doc_max_bytes (32 KiB default) caps the total across the project files — the crossing file is prefix-truncated and every file after it is skipped, with no warning anywhere in the TUI. Because files are concatenated root-first, the ones cut are those nearest your startup directory, so you lose your most specific instructions while the general root-level ones survive. In Claude Code, only the first 200 lines of auto-memory MEMORY.md are loaded. Keep each file focused.

Where to go next with documentation as context

Section titled “Where to go next with documentation as context”
Pruning CLAUDE.md and AGENTS.md The other direction: what to delete, what to move to subdirectory files and skills, and nine prompts that do the cutting.
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.

Written by

See what's new on the platform.

Privacy Policy Terms of Service Cookie settings