Structuring, organizing, and standardizing technical knowledge in software projects allows different developers and AI agents to work according to the same architectural decisions, conventions, contracts, and procedures, without rediscovering how the system works for every task.

The proposal is to establish a consistent, accessible knowledge base integrated into the project itself, guiding development regardless of who executes the work or which AI tool is used.

1. The project as a source of context

A project prepared to work with AI agents should provide its own instructions and technical references.

Information such as technologies used, architecture, adopted libraries, implementation patterns, contracts, and procedures should not depend exclusively on developer knowledge or instructions manually supplied for each session.

This information needs to be available in the repository itself or in shared sources accessible to agents.

This allows a developer newly joining the project to use AI for tasks without previously knowing every technical decision in the system.

The goal is not to eliminate the need to understand code but to prevent each agent from investigating decisions already made and documented.

Project knowledge should be reusable, independent of the developer and agent used.

2. Knowledge structure and hierarchy

Concentrating all documentation in one file can complicate maintenance and increase unnecessarily loaded information.

A more efficient approach organizes context at different levels.

Global context

Information applicable to the entire project:

  • Overall architecture and module organization.
  • Languages, frameworks, and technologies.
  • Shared conventions.
  • Security rules.
  • Architectural constraints.
  • Common tools and procedures.

Specific context

Information related to particular areas:

  • Frontend and interface libraries.
  • Backend, services, and business rules.
  • Database and persistence.
  • Infrastructure and deployment.
  • External integrations.
  • Tests and quality.

Module context

Documentation of responsibilities, contracts, decisions, and behaviors specific to parts of the system.

This organization lets agents locate relevant task information without loading all project knowledge.

Hierarchy also facilitates maintenance: a system-wide decision should be documented in a shared reference, while a specific convention can remain near its corresponding module.

3. Contracts, conventions, and architectural decisions

Documentation needs to record not just which technologies are used but decisions determining how they should be applied.

Knowing a project uses React and TypeScript, for example, does not tell the agent which components to reuse, how to organize state management, or which API communication patterns are established.

The same applies to backend: knowing the language and framework is insufficient to identify where to implement business rules, which services to reuse, or how to handle authentication and errors.

Technical context should cover, according to project needs:

  • Approved technologies and libraries.
  • Module structure and responsibilities.
  • Implementation patterns.
  • API contracts and schemas.
  • Naming conventions.
  • Architectural decisions and their rationale.
  • Constraints and solutions that should not be used.

Important architectural decisions can be recorded in ADRs (Architecture Decision Records) or equivalent documents.

Contracts should preferably use verifiable formats such as OpenAPI, JSON Schema, or shared type definitions.

The agent should have autonomy to implement solutions within existing standards, not to redefine architecture for every task.

When a change requires altering an established decision, it should follow the project's defined review process.

4. Sources of truth and conflict resolution

One of the main risks in documentation used by agents is contradictory or outdated information.

One document may require a library while another recommends an alternative. An API contract may show fields already modified. An old instruction may recommend a pattern no longer used.

In these situations, the agent may follow an incorrect reference and produce changes incompatible with the system.

To reduce this problem, establish sources of truth for each information category.

For example:

  • API contracts maintained in dedicated specifications.
  • Architectural decisions recorded in specific documents.
  • Conventions organized by area or module.
  • General instructions centralized at an entry point.
  • Delivery requirements associated with the respective ticket.

Whenever possible, avoid duplicating rules. Specific documents should reference shared information instead of reproducing it.

Conflict handling also needs definition.

A specific instruction can complement a global rule within its scope but should not contradict a mandatory constraint without an explicit decision.

When two sources present incompatible information and no valid precedence rule exists, the agent should flag the divergence instead of arbitrarily choosing one.

Reliable context depends not only on information availability but also on its consistency and authority.

5. AGENTS.md as an entry point

AGENTS.md can serve as an entry point for development agents, gathering general instructions and references to the rest of the project's knowledge.

Its role should not be concentrating all technical documentation.

It should guide the agent on how to work in the repository, which rules must be respected, and where to find specific information.

Elements that may belong in this file include:

  • Architecture and technology overview.
  • Technical documentation location.
  • Mandatory conventions.
  • Constraints and prohibited practices.
  • Contract and schema references.
  • Available skills and procedures.
  • Validation commands.
  • Rules for architectural changes.
  • Context update procedures.

An agent receiving a frontend task, for example, should be able to identify through AGENTS.md where to find interface instructions, available components, API contracts, and test procedures.

This avoids indiscriminate repository exploration to discover conventions that could already be documented.

Mandatory context updates

An especially important rule is establishing that code changes must be accompanied by updates to affected context information.

AGENTS.md should direct the agent to check, before completing any implementation, whether its changes affected:

  • Architecture or module organization.
  • API contracts and schemas.
  • Implementation conventions and patterns.
  • Business rules.
  • Operational procedures.
  • Existing instructions and skills.

When there is an impact, corresponding documents should be updated as part of the delivery itself.

This includes reviewing or removing obsolete instructions and checking for contradictions with other references.

It does not mean changing documentation with every code change. It means every change should undergo a context impact check.

This rule should also be part of task completion criteria.

6. Context specific to area and task

After identifying general instructions, the agent should retrieve knowledge related to its task.

Frontend work may require context about components, design system, state management, routes, and API contracts.

A backend change may need information about services, persistence, authentication, and business rules.

An infrastructure operation may depend on deployment procedures, environment configuration, and security constraints.

These information sets do not need simultaneous loading.

One strategy is keeping references by area or module so the agent consults corresponding context upon identifying task scope.

Directory-specific project instructions can also be used, depending on development tool capabilities.

Documentation should indicate which information is mandatory for particular operations and which can be consulted as needed.

The goal is letting the agent quickly find applicable standards without reconstructing them through extensive code analysis.

This does not eliminate reading implementation-related files. Code remains necessary to understand current feature state.

Documentation provides decisions and references; code analysis provides the concrete context of the change.

7. Skills and tools as complementary resources

Skills are not a structure for organizing project context. They provide specialized instructions, procedures, and resources for performing particular tasks.

For example, an agent can use a skill to run browser tests, prepare a migration, or generate an artifact in a specific format. Project documentation identifies the contracts, standards, and constraints these operations must respect.

AGENTS.md can point to available skills without reproducing their instructions. When supported by the tool, the agent loads the applicable skill only when needed.

Tools and integrations are also complementary: they provide access to systems and actions, but do not replace sources of truth about project architecture and behavior.

For more on this distinction, see Harnesses, skills, tools, and MCP.

8. Selective retrieval and context continuity

Even with a well-organized structure, loading all documentation into every execution may be unnecessary.

Context engineering should allow relevant information to be located and retrieved as work progresses.

Retrieval may happen through direct references, directory navigation, search tools, or indexing mechanisms.

The strategy depends on project size and available infrastructure.

For smaller projects, a clear document and entry-file structure may suffice.

Large projects or those distributed across repositories may benefit from additional mechanisms to locate information and connect documents.

Continuity across sessions

Another challenge is preserving important information when execution is interrupted, context is compacted, or work transfers to another agent.

Decisions made, changes implemented, problems found, and pending work should not depend exclusively on conversation history.

This information can be recorded in planning, state, or execution tracking files.

However, permanent project knowledge must be separated from temporary work information.

An approved architectural decision belongs to persistent system context.

Progress on a specific implementation belongs to that execution's context.

Mixing these information types can create excessive documentation and complicate identifying references that remain valid.

Several approaches apply similar principles to different parts of the work:

  • CHAOS: a convention for structuring and maintaining persistent technical project knowledge, including architecture, rules, contracts, and decisions.
  • Spec-Driven Development (SDD): uses specifications as a reference for planning, implementing, and validating changes.
  • File-System-Based (FSB): uses files to preserve plans, progress, checkpoints, and other information needed for continuity across agent executions.

FSB is used here as a description of file-based persistence, not as the name of a standardized methodology. Files can also store reusable memory and permanent knowledge; their purpose depends on their contents and maintenance rules.

These approaches can coexist, with different responsibilities. Canonical context describes the system; specifications describe what must be delivered; execution records track ongoing work.

None is a prerequisite for organizing project context. What matters is keeping references reliable, accessible, and up to date without duplicating information.

10. Example repository organization

A simple structure can combine an agent entry point with technical references organized by area, without requiring a particular convention:

project/
├── README.md
├── AGENTS.md
├── docs/
│   ├── architecture/
│   │   └── overview.md
│   ├── contracts/
│   │   └── openapi.yaml
│   ├── frontend/
│   │   └── guidelines.md
│   └── backend/
│       └── guidelines.md
├── frontend/
├── backend/
└── tests/

Names and directories are illustrative. An equivalent organization can use existing documents, external references, or conventions such as CHAOS without duplicating contracts and rules.

Example: frontend implementation

When assigned to develop a component, an agent can:

  1. Consult AGENTS.md to locate applicable rules and references.
  2. Read frontend documentation and required contracts.
  3. Analyze existing code and implement the change.
  4. Use specialized tools or skills when the task requires them.
  5. Run tests and check whether technical documentation was affected.

This sequence can be adapted to the project; the essential point is consulting the right sources before changing the system.

11. Updating context during development

Documentation tends to lose reliability when maintenance depends on occasional initiatives.

In projects with agents, this problem may be amplified: an outdated instruction may be reused across several implementations before someone identifies the discrepancy.

Context updates should therefore be part of normal development flow.

Whenever a delivery modifies documented decisions, contracts, behaviors, or procedures, affected references should be updated alongside implementation.

This responsibility can be established through persistent AGENTS.md instructions, acceptance criteria, and code review checks.

A practical rule is:

No implementation should be considered complete without checking whether affected technical context remains correct.

This does not require new documents for every change. Often updating an existing reference is enough.

It is also important to avoid indiscriminately incorporating temporary information into permanent documentation.

Discarded plans, implementation attempts, and findings without future relevance do not necessarily need to become canonical project knowledge.

Updates should preserve what will be useful and reliable for subsequent work.

12. Knowledge validation and governance

Keeping documents organized does not guarantee their information remains correct.

Context also needs review and validation mechanisms.

Some checks can be automated:

  • Identifying nonexistent links and references.
  • Validating schemas and contracts.
  • Checking documented examples and commands.
  • Detecting references to removed files.
  • Comparing contracts and implementations when suitable tools exist.
  • Identifying documentation affected by changes to relevant modules.

Other checks depend on technical review, especially those involving architectural decisions or business rules.

It is also worth assigning owners to documents or knowledge areas, particularly in projects with multiple teams.

When a change modifies a source of truth, other dependent references need evaluation.

Governance should not make documentation bureaucratic. Its goal is preserving the reliability of instructions used during development.

Conclusion

Context architecture defines how project technical knowledge is organized and connected.

Context engineering determines how this information is located, selected, and made available to agents.

Documentation maintains decisions, rules, contracts, and procedures guiding implementations.

With a consistent structure, developers at different experience levels can use AI agents without relying exclusively on informal knowledge or lengthy investigations into system behavior.

Approaches such as CHAOS, SDD, and FSB can complement this organization for different purposes. Skills and tools support task execution without replacing technical system documentation.

However, the structure remains useful only when updated alongside code and when mechanisms exist to identify contradictory or obsolete information.

The goal is to make technical context a permanent part of project architecture: organized, accessible, verifiable, and continuously updated so humans and agents work according to the same standards and decisions.

Sources and further reading