Chapter 2: Context as Infrastructure

The Fundamental Principle

In traditional development, infrastructure means servers, databases, load balancers, and CDNs. In AI-native development, context is infrastructure. The quality and structure of your context directly determines how effectively agents can work.

Poor context produces poor results. Excellent context produces remarkable results. The difference is not marginal - it is exponential.

What Is Context?

Context encompasses everything an agent needs to understand your project:

Project Context

* Technology stack (frameworks, languages, tools)
* Architecture patterns (MVC, microservices, serverless)
* File structure and organization
* Dependencies and versions
* Build and deployment processes

Code Context

* Coding standards and conventions
* Design patterns in use
* Common utilities and helpers
* API integration patterns
* Error handling approaches

Business Context

* Domain concepts and terminology
* Business rules and logic
* User workflows
* Compliance requirements
* Performance constraints

Historical Context

* Why certain decisions were made
* Known issues and workarounds
* Technical debt and refactoring plans
* Lessons learned from incidents

Markdown Is the Substrate

Markdown has become the de facto standard for AI-native organizations. It is token-efficient, easily parsed, and both human- and machine-readable. Strategic plans, architecture decisions, and product roadmaps belong in version-controlled .md files. Markdown carries the human-readable context; JSONL carries the machine-readable side - eval logs and agent traces. Together they are the substrate for building with AI. Requirements become code, written in a language both humans and agents understand.

The Cost of Poor Context

Without adequate context, agents will generate code that does not match your patterns, miss business rules, suggest incompatible implementations, fail to reuse existing utilities, and require extensive revision. This is not AI failure - it is context failure. The same agent that produces unusable code with poor context produces production-ready code with excellent context.

Context ROI

Investing in context infrastructure pays exponential dividends:

One-Time Investment

* 2-4 hours to create initial CLAUDE.md / AGENTS.md
* 1-2 hours to document architecture patterns
* 30 minutes to configure tool and MCP settings

Ongoing Benefits

* 30-50% reduction in revision cycles
* 40-60% more accurate initial generations
* 70-90% less time explaining context in prompts
* Faster onboarding for new team members and new agents
* Better code consistency across the project

For a 6-month project with a 4-person team, good context infrastructure saves hundreds of developer hours. The return on a few hours of investment is enormous.

Context Layers

Effective context architecture uses layers:

Layer 1: Project Root Context (CLAUDE.md / AGENTS.md)

Global project information that applies everywhere - your project's constitution.

Layer 2: Module/Feature Context

Specific to subsystems or features: authentication patterns, payment rules, admin conventions. Nested context files take precedence over root in their subtree.

Layer 3: File/Component Context

Inline documentation for specific implementations - JSDoc, docstrings, or language-appropriate formats.

Layer 4: Session Context

Temporary context provided for a specific task. Ephemeral, not persisted.

Agents pull from all layers, with more specific context overriding general context when conflicts arise.

Context Best Practices: Guardrails, Not Manuals

Creating effective context files requires understanding their purpose: they are API contracts for AI, not reference manuals for humans. This changes everything about how you write them.

Guardrails Over Manuals

Keep context high-level and strategic. Document what AI consistently mishandles. If an explanation needs more than three paragraphs, the tooling - not the documentation - needs improvement.

Bad: ten paragraphs explaining a complex CLI command.
Good: a wrapper script with a cleaner API, documented in two sentences.

Strategic References, Not Embedded Content

Avoid embedding entire files. Context windows are precious even at a million tokens, because relevance still degrades with noise.

Instead of: [Paste entire 500-line database error handling guide]
Use: "For database errors, see /docs/db-errors.md"

Prioritize code over prose in token allocation. Agents can read code directly when needed.

Prescriptive Guidance, Not Restrictions

Never restrict without providing alternatives. Negative-only guidance frustrates both AI and humans.

Bad: "Don't use --force flag"
Good: "Prefer --safe-mode for most operations; use --force only in dev with team lead approval"

Context Window Hygiene

Use simple, transparent approaches over opaque compaction. Restart sessions with a focused catch-up, dump state to markdown for complex work, and provide only relevant files for the current task.

Plan Before Implementation

Use planning mode for large changes. Align on approach and define checkpoint reviews before coding begins. This prevents wasted effort on wrong approaches.

Version Control for Context

Treat context files as code: review them in pull requests, test their effectiveness, document breaking changes, and keep them current. Stale context is worse than no context - agents will follow outdated patterns confidently.

Test and Iterate

Context effectiveness is empirical. Give an agent a task, evaluate the output, identify misunderstandings, update the context, and repeat until behavior matches intent. Context files are living infrastructure - review them quarterly and whenever patterns change.