THE AI-NATIVE SOFTWARE DEVELOPMENT PLAYBOOK
Chapter 04
Context engineering and the agent-ready project
Give agents the right context, not unlimited access.
Create a reliable project knowledge base with enforceable permissions.
Context is a maintained system asset
Even a powerful model cannot reliably infer undocumented policy, historical decisions or local conventions. Context engineering is the work of supplying the right information at the right time and keeping it authoritative. More context is not automatically better: stale, contradictory, irrelevant or malicious instructions can degrade execution and introduce security exposure.
The minimum useful context set
- Product: intended users, outcomes, requirements and approved scope.
- Architecture: system boundaries, interfaces, data models and recorded decisions.
- Engineering: conventions, run instructions, dependencies and test commands.
- Controls: data sensitivity, access policy, change approval and prohibited actions.
- Operations: deployment process, health indicators, support ownership and rollback.
A practical repository pattern
A small team might maintain the following files; larger teams can distribute them across existing approved systems of record:
- README.md — setup, objectives and project map
- docs/intent.md — approved business outcome and scope
- docs/requirements.md — numbered requirements and acceptance criteria
- docs/architecture.md — system boundaries and interfaces
- docs/decisions/ — architecture decision records
- docs/security.md — threat assumptions, roles and controls
- docs/runbook.md — deployment, recovery and support
- tests/ — automated acceptance, unit and security checks
- AGENTS.md or equivalent — scoped agent instructions, not security policy enforcement
The agent’s instructions should define how to inspect the repository, what evidence to return and which actions require permission. They cannot replace tool-enforced access control. Treat third-party text, tickets, retrieved documents and tool output as untrusted data even if the agent reads them in the same session.
Making a repository portable across coding agents
Use a small, reviewed repository-wide instruction contract for shared engineering expectations: scope, conventions, relevant requirements, tests, and expected evidence. Agents may need platform-specific adapters such as CLAUDE.md or local configuration files, but these should reference the shared contract rather than introduce contradictory requirements. Tool behaviour and supported file names vary by product and version.
The portable boundary is procedural, not a claim of identical tool behaviour. Keep credentials out of version control; scope MCP connections, file access and execution privileges using controls external to the model; and record which configuration was active for any reproducible example. A file saying “do not deploy” does not block a deployment. CI checks, branch protection, sandboxing and permissions must enforce the boundary.
IN PRACTICE ServiceFlow uses AGENTS.md as its shared guide, adds a minimal CLAUDE.md adapter, and provides docs/coding-agent-setup.md with a reproducible review exercise. The book avoids installation commands and rapidly changing permission-mode names. Readers should consult current official documentation for their own coding-agent environment.
Context hygiene
Assign owners to critical documents. Keep decisions in version control or an auditable system. Prefer short task-specific context over enormous generic prompts. Link each requirement to its tests and review evidence. Remove obsolete instructions and redact credentials and sensitive customer records from agent-accessible files.
In ServiceFlow, the agent receives the roles matrix and explicit restriction that only authorised approvers may update a request. It receives synthetic test data and a sandbox database rather than live employee records.
IN PRACTICE Before adding more agents, identify the authoritative source for each requirement, decision and control. If the team cannot locate it, the agent probably cannot reliably use it.
Research basis: Atlassian [4], Google [5], Anthropic [1], OpenAI [6].
Control context before it reaches the model
An agent should not ingest every file simply because it can. Relevant context must be discovered from approved sources, permission-checked, and labelled by authority and freshness. A current architecture decision is more authoritative than a two-year-old chat snippet. A test fixture may contain synthetic data, while a production log may contain personal information and should not be copied into an unapproved model environment.
- Source of truthRequirements, decisions, standards and codeMAINTAIN
- Task contextRelevant, current, minimal informationSELECT
- Enforced permissionsRead/write paths, tool policy and secretsCONTROL
- Evidence trailChanges, tests, limitations and approvalsRECORD
Context failure modes
Watch for stale documentation, contradictory instructions, inaccessible dependencies, overlong context dumps and hidden assumptions. A useful corrective loop is: identify the missing fact, locate its authoritative owner, update the source of truth, rerun the task, and retain the clarification for later work. Repeating the same clarification privately inside a prompt is not a durable organisational solution.