Why architecture notes, onboarding docs, and AI instructions should overlap , but not be the same thing
More like this: AI in practice — collection: Tools, agents, workflows, and engineering judgment
Most teams still treat documentation as one job: write the system down so people can understand it. When AI agents enter the workflow, the default move is to point them at the same docs and hope those docs can do a second job.
They usually cannot.
Human-facing documentation and agent-facing guidance share a source of truth: the actual system, including code, config, infrastructure, decisions, and operational practice. But they are different representations of that truth. They serve different readers, operate under different constraints, and fail in different ways.
Conflating the two usually produces one of two bad outcomes. You duplicate everything and watch the copies drift apart, or you make the docs so generic that neither engineers nor agents get useful guidance.
This article lays out a practical framework for maintaining both layers. It covers what belongs in each, where deliberate overlap is necessary, how to translate between them without creating a maintenance problem, and how to keep the system from rotting.
The problem: one set of docs, two different readers
When an engineering team documents a system, the implicit audience is a human engineer: someone joining the team, debugging an incident, or making a design decision six months from now. Good human docs build a mental model. They explain why the pricing engine splits requests across two services, not only that it does. They preserve the reasoning behind a migration, the tradeoffs that shaped a schema, and the organizational context behind an API boundary.
Those qualities make them valuable for engineers. They also make them poor direct instructions for an agent.
An agent does not need the full story during most tasks. It needs to know what it may do, what it must not do, and how to handle the recurring decisions it will face. An agent operating on your codebase needs compact, unambiguous, operationally scoped guidance, not a narrative about the 2023 database migration.
The mismatch is predictable. Teams paste an architecture wiki into a system prompt and wonder why the agent still makes bad decisions. Or they write terse rules with no connection to the living docs, and those rules go stale within weeks.
The issue is not that one format is better. Human docs and agent guidance are different instruments. Treating them as one artifact gives you weak documentation and weak automation.
What human docs actually do
Human-facing documentation carries several jobs that are hard to replace with generated summaries or rule files.
Onboarding and orientation. A new engineer reads the architecture overview to build a working model of the system. The doc explains the current state, but also the trajectory: what changed, what is planned, what was tried, and what was abandoned. That context turns isolated facts into understanding.
Debugging and incident response. When something breaks at 2 AM, the engineer needs to understand why the system behaves the way it does. A note such as “we split the write path because the legacy system cannot handle concurrent updates to the same account” may be the fastest path to a useful diagnosis.
Design and decision support. Architecture decision records, design docs, and technical RFCs help future engineers understand the constraints behind past choices. Without them, new work can easily reintroduce a problem that was already solved or violate an invariant nobody remembers.
Institutional memory. Some knowledge exists only in docs. The person who understood the billing reconciliation pipeline may be gone. Their document may now be the only useful record of how the system works and what assumptions it depends on.
Human docs are contextual and narrative. They reward careful reading. They can also be verbose, unevenly maintained, and hard for automated systems to consume reliably.
What agent guidance actually does
Agent-facing guidance has a narrower operational job. It tells an automated system how to behave inside a bounded scope. Good agent guidance has a few specific properties.
It is compact. An agent working on a pull request does not need the history of the authentication system. It may only need this: passwords use bcrypt with cost factor 12 or higher; sessions expire after 30 minutes of inactivity; the auth module must not import from billing. For the task at hand, that may be the relevant universe.
It is behavioral. Human docs describe what exists and why. Agent guidance tells the agent what to do, what to avoid, and when to stop. “Our pricing model supports three tiers” is a fact. “When modifying pricing logic, never remove a tier without explicit approval; preserve backward compatibility for existing subscriptions” is an operational rule.
It encodes recurring decisions. Agents repeatedly hit the same choice points: which test framework to use, how to handle nullable fields, where to place a new endpoint, when to extend a service versus creating a new one. Good guidance pre-resolves these routine decisions so the agent does not infer them from scattered context.
It defines boundaries. The most important function of agent guidance is often restraint. It should tell the agent where to stop and ask for review: “If the change touches the payment processing pipeline, stop and request human approval before proceeding.” Boundaries are safety constraints. They need direct language.
The overlap: what must exist in both
Human docs and agent guidance serve different purposes, but they cannot be independent. Certain facts belong in both representations because inconsistency there causes real damage.
Invariants. An invariant is a property of the system that must remain true. “Every customer record must have a unique, non-null email address.” “The billing service must not call the user service directly; all communication goes through the event bus.” These are load-bearing architectural rules. Engineers need to understand them, and agents need to obey them.
Safety constraints. Rules that prevent catastrophic outcomes must be explicit everywhere: data deletion safeguards, rate limits, deployment restrictions, production access rules. If the human docs say “do not deploy to production on Fridays” but the agent guidance omits it, the gap will eventually matter.
Canonical definitions. Domain-specific language needs one authoritative meaning. If “active subscription” means status = active and end_date is null or in the future, both humans and agents need that same definition. Otherwise, one reader is reasoning about a different system.
Key boundaries and ownership. Service ownership, public versus internal APIs, stable versus experimental components, and review requirements shape both engineering judgment and agent behavior.
This overlap is not duplication for convenience. It is intentional redundancy where inconsistency is expensive.
The split-doc architecture
A practical documentation system keeps the two representations separate while deriving them from the same body of project knowledge.
The translation layer is the important part. It is not necessarily a tool or script. It is the practice of taking rich human documentation and distilling the operational rules an agent needs. It also works in the other direction: when agent behavior exposes a gap or contradiction, that signal should feed back into the human docs.
This should be continuous and lightweight, not a one-time migration. Every meaningful system change should trigger a small review: does this affect human docs, agent guidance, both, or neither?
Translating human docs into agent guidance
Translation from human docs to agent guidance is not summarization. It is a change of interface. You are not making the doc shorter. You are extracting a different kind of information from the same material.
Suppose the human-facing documentation for a pricing system says this:
Pricing Architecture
The pricing engine was redesigned in Q3 2023 to support multi-currency billing after the APAC expansion. The legacy system used a single
price_centscolumn denominated in USD; the new system stores prices in apricestable withcurrency,amount, andeffective_datecolumns. Migration was completed in November 2023, but some older accounts may still have records referencing the legacy schema.
Pricing changes are propagated through the event bus to the invoice service and the analytics pipeline. The invoice service is the system of record for finalized prices; the pricing engine is authoritative only for current prices.
Three pricing tiers exist: Free, Pro, and Enterprise. The tier definitions live in the
pricing_tiersconfig and must not be modified without product and finance approval. Historically, we experimented with a “Starter” tier in early 2023, but it was deprecated before launch. References to it may still exist in test fixtures.
All pricing logic must preserve backward compatibility for existing subscriptions. A customer on a legacy plan must never see their price change without explicit notification and a 30-day grace period.
The derived agent guidance might look like this:
## Pricing Rules
- Prices are stored in the prices table with columns: currency, amount,
effective_date. Do not use the deprecated price_cents column for new logic.
- The pricing engine is authoritative for current prices only. The invoice
service is the system of record for finalized prices.
- Three tiers exist: Free, Pro, Enterprise. Tier definitions are in
the pricing_tiers config. Never add, remove, or rename a tier without
explicit product and finance approval.
- Treat “Starter” as a deprecated, never-launched tier. Do not reintroduce it.
Existing test fixtures may still mention it.
- Preserve backward compatibility for existing subscriptions.
- If a change would alter the price seen by an existing customer, stop and
request review.
- Pricing changes propagate through the event bus. If modifying event
payloads, verify that the invoice service and analytics pipeline still
receive the fields they expect.
The history is gone: APAC expansion, Q3 2023, the migration timeline. The agent usually does not need that material while editing code. The operational rules remain: use the current table, respect service authority, preserve tier boundaries, protect existing subscriptions, and verify downstream event consumers.
This is translation, not compression.
Deriving agent guidance: arepeatable process
When you create or update agent guidance from human docs, look for four categories of information.
Invariants. What must always be true? These become hard rules: “Every API response must include a request_id header.” “The users table must not be written directly; all mutations go through UserService.”
Recurring decisions. What choices come up repeatedly during development? These become defaults: “Use pytest for Python tests.” “New endpoints go in the v2 API namespace.” “Feature flags are managed through LaunchDarkly, not ad hoc environment variables.”
Boundaries. Where must the agent stop and defer to a human? These become halt conditions: “If a migration would drop a column, stop and request review.” “If a change touches the payment pipeline, require explicit approval.”
Standard procedures. What steps should be followed for common tasks? These become checklists: “To add a new API endpoint, create the route handler, add input validation, write integration tests, update the OpenAPI spec, and add the endpoint to the rate limiter configuration.”
Everything else stays in the human docs: the narratives, the history, the design rationale, and the “why we chose Postgres over MongoDB” discussions. That context is useful for engineers. It is often noise for agents.
What should never be flattened
Some information resists translation into compact rules. Flattening it can remove the context that made the guidance safe.
Domain language and its nuances. A human doc may explain that “active” means one thing in billing and another in identity. An agent rule that says “check whether the account is active” without specifying the relevant definition is a bug waiting to happen. The human explanation should remain intact, and the agent guidance should include the exact definition needed for the task domain.
Architecture tradeoffs. A doc might say, “We chose eventual consistency for notifications because strong consistency would require synchronous calls to three downstream services and add latency to every user action.” An agent working in the notification system needs to know the system is eventually consistent and should not introduce synchronous cross-service calls casually. The full tradeoff still belongs in the human docs, because the next engineer proposing a consistency change needs the reasoning.
Migration rules and transition states. Systems in the middle of a migration often carry temporary rules: “The old authentication flow is still active for customers onboarded before March 2024; the new flow applies to everyone after.” Agent guidance can encode the current rule, but the human doc needs to explain the transition, the planned end state, and the criteria for removing the old path.
Compliance and regulatory constraints. “We retain financial records for seven years per SOX requirements” cannot safely become only “do not delete records.” The agent needs the deletion boundary. The human doc needs the regulatory basis, retention periods by record type, and audit response process.
What to duplicate vs. what to translate
A useful split is to decide whether a piece of knowledge should be duplicated, translated, kept human-only, or kept agent-only.
Duplicate: present in both, possibly worded differently but semantically identical
- System invariants and safety constraints
- Canonical definitions of domain terms
- Service ownership and responsibility boundaries
- Security rules and access control policies
Translate: rich human context becomes compact operational guidance
- Architecture descriptions → behavioral rules and boundaries
- Design rationale → pre-resolved decisions
- Operational procedures → step-by-step checklists
- Incident postmortems → updated rules, tests, and halt conditions
Human-only: useful for engineering judgment, not direct agent execution
- Historical context and migration narratives
- Design alternatives that were considered and rejected
- Onboarding guides and learning paths
- Strategic roadmaps and future plans
- Exploratory analyses and research notes
Agent-only: execution scaffolding with little long-term explanatory value
- Tool configuration and invocation syntax
- Prompt formatting rules and output constraints
- Context-window and token-budget conventions
- File path conventions for automated tasks
A sample repository layout
Organization matters because both audiences need to find the right material without reading everything. One workable layout looks like this:
docs/
├── architecture/
│ ├── overview.md # Human: system architecture narrative
│ ├── decisions/
│ │ ├── 001-event-bus.md # Human: ADR for event bus choice
│ │ └── 002-multi-currency.md # Human: ADR for pricing redesign
│ └── diagrams/
│ └── system-context.mmd # Shared: architecture diagram
├── guides/
│ ├── onboarding.md # Human: new engineer onboarding
│ ├── incident-response.md # Human: incident handling
│ └── deployment.md # Human: deployment procedure
├── agent-guidance/
│ ├── CONVENTIONS.md # Agent: coding conventions and defaults
│ ├── BOUNDARIES.md # Agent: halt conditions and review triggers
│ ├── INVARIANTS.md # Agent: system invariants and safety rules
│ └── PROCEDURES.md # Agent: task checklists
├── shared/
│ ├── glossary.md # Shared: canonical domain definitions
│ ├── service-ownership.md # Shared: ownership boundaries
│ └── security-policies.md # Shared: security rules
└── MAINTENANCE.md # Meta: update process and ownership
The shared/ directory contains definitions and facts that must remain consistent across both audiences. The agent-guidance/ directory stays small and focused; it is not a second architecture wiki. MAINTENANCE.md documents the update process, which is part of the system rather than an afterthought.
Keeping it alive: governance without bureaucracy
Documentation drift is the default. Human docs and agent guidance will diverge unless the team makes drift visible and cheap to fix.
One source of truth, two representations. The real system is the source of truth: code, configuration, infrastructure, production behavior, and operational practice. Human docs and agent guidance are representations of that truth. When the system changes, both representations should be checked.
Attach doc updates to the change process. The most reliable way to keep docs current is to make documentation review part of the pull request or change request workflow. A PR template can ask two simple questions: “Does this change affect human docs?” and “Does this change affect agent guidance?” Most changes will not require updates, but the habit matters.
Use automated checks for critical invariants. For the most important rules, consider lightweight enforcement. CODEOWNERS can require review when INVARIANTS.md or BOUNDARIES.md changes. CI can check that referenced file paths, service names, table names, or glossary anchors still exist. These checks will not prove the docs are correct, but they can catch obvious drift.
Assign ownership. Give the agent guidance files a clear owner: a person, platform team, architecture group, or rotating maintainer. Once a quarter, that owner should review the guidance against recent system changes and update anything that has drifted. This should be a small maintenance task, not a documentation project.
The maintenance process should stay small. If it adds more than a few minutes to an ordinary change, people will route around it.
The deeper point
Documentation has always managed the gap between what exists and what people understand. AI agents add a second audience with different needs and different failure modes.
The temptation is to treat this as a tooling problem: find the right format, template, or automation, and the docs will maintain themselves. Tooling helps, but the hard work is deciding what matters for each audience: what must be duplicated for safety, what should be translated for execution, and what should remain in one place.
A team that gets this right ends up with a layered documentation system. Rich human docs help engineers understand the system and make decisions. Compact agent guidance helps automation act safely inside known boundaries. The translation practice between them keeps both grounded in the same operational reality.
That is not a revolution in documentation. It is an extension of the principles that already make docs useful: clear purpose, appropriate detail, explicit ownership, and regular maintenance. The difference is that your documentation now has two real audiences. Serving both well means acknowledging the split instead of pretending one artifact can do everything.
Write docs for humans that help humans think. Write guidance for agents that helps agents act. Keep them connected, keep them honest, and keep them maintained.