Contents

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

A practical repository pattern

A small team might maintain the following files; larger teams can distribute them across existing approved systems of record:

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.

  1. Source of truthRequirements, decisions, standards and codeMAINTAIN
  2. Task contextRelevant, current, minimal informationSELECT
  3. Enforced permissionsRead/write paths, tool policy and secretsCONTROL
  4. Evidence trailChanges, tests, limitations and approvalsRECORD
Figure 1. The four layers of an agent-ready context system. Original illustration.

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.

top