CHAOS
Context for Human-AI Organization of Systems
CHAOS (Context for Human-AI Organization of Systems) is an open convention for organizing the knowledge needed to understand, develop, maintain, and evolve software systems.
It establishes a persistent, structured source of context independent of models, IDEs, or development tools.
Code contains the implementation. CHAOS contains the context needed to understand and evolve the system.
This includes architectural decisions, business rules, contracts, integrations, responsibilities, and constraints that cannot always be identified by reading the code alone.
1. Why use CHAOS?
Coding agents can investigate repositories and interpret existing implementations. However, they cannot always determine why an architecture was chosen, which behaviors are intentional, or which decisions must be preserved.
That information is often scattered across documents, tickets, conversations, and developers' knowledge. CHAOS provides a structure to make it accessible and persistent.
The goal is to avoid making every new developer or agent reconstruct an understanding of the system from scratch. It also reduces reliance on conversation histories and makes it easier for different agents to work on the same project.
2. How CHAOS organizes context
The convention uses three main elements:
project/
├── README.md
├── AGENTS.md
└── .chaos/
| Element | Responsibility |
|---|---|
README.md |
Entry point for humans: overview, installation, and usage |
AGENTS.md |
Entry point for agents: instructions and context locations |
.chaos/ |
Canonical source of knowledge about the system |
When a contract or specification already has an official source in the project, such as an OpenAPI definition, CHAOS can reference it instead of duplicating its content.
AGENTS.md should remain concise. Its responsibility is to direct agents to the information they need, rather than reproduce all the documentation.
The internal structure of .chaos/ depends on the project. For example:
.chaos/
├── architecture/
│ └── system-boundaries.md
├── business/
│ └── order-lifecycle.md
├── features/
│ └── checkout.md
├── contracts/
│ └── public-api.md
└── integrations/
└── payment-provider.md
These categories are illustrative. There is no need to create directories or documents for concepts the project does not have.
Reference: CHAOS — Official repository
3. Context is not a copy of the code
A central CHAOS rule is to record knowledge relevant to understanding the system without reproducing its implementation.
Consider an ecommerce application using Stripe. The code may show how payments are created, while CHAOS can establish that:
- The backend is responsible for creating payments.
- The frontend cannot create charges directly.
- Webhooks may be delivered more than once.
- An order can only be marked as paid after backend confirmation.
- Other services depend on this behavior.
This information guides agents during changes and helps prevent technically valid implementations that violate system rules.
CHAOS also establishes a single canonical source for each concept. Other documents should reference shared information instead of maintaining independent copies.
4. Context shared across projects
In systems composed of multiple repositories, some knowledge belongs to an individual project while other knowledge must be shared. CHAOS allows these responsibilities to be separated:
company-api/
├── AGENTS.md
└── .chaos/
company-app/
├── AGENTS.md
└── .chaos/
company-admin/
├── AGENTS.md
└── .chaos/
company-shared-chaos/
├── contracts/
├── integrations/
├── branding/
└── shared/
Each repository maintains its local context. Contracts between applications, shared rules, integrations, and other common knowledge can live in a shared CHAOS repository.
For example, if an API changes a contract used by an application and an administration dashboard, agents should consult the same canonical specification before modifying their respective projects. This helps prevent incompatible interpretations of the same rule.
5. How agents use and maintain CHAOS
The expected workflow is simple:
- Read
AGENTS.md. - Identify the
.chaos/documents relevant to the task. - Consult shared context when necessary.
- Investigate the code and carry out the work.
- Update CHAOS when canonical behavior, contracts, or system decisions change.
Agents do not need to load every document on every run. They should retrieve only the necessary context, reducing unnecessary reads and token consumption.
Updating knowledge
Documentation must evolve with the system. If an implementation changes a contract or business rule, the corresponding CHAOS update should be part of the delivery.
Git preserves the history of these changes. CHAOS maintains the current description of the system. Checkpoints, tickets, and temporary execution records should remain distinct from canonical knowledge.
6. CHAOS and skills have different responsibilities
Skills represent capabilities or procedures an agent can use. CHAOS describes the system where those capabilities will be applied.
For example, an agent may know how to implement payment integrations. CHAOS tells it which services own payments in that project and which constraints must be respected.
Skills provide capabilities. CHAOS provides context.
Agents can use this information to determine which tools, skills, or knowledge a task requires. CHAOS does not require creating skills for procedures an agent already knows.
7. Adopting CHAOS in an existing project
The official repository provides a prompt to guide an agent through adoption in two phases.
First phase — diagnosis and planning
The agent investigates the repository, identifying architecture, rules, contracts, integrations, and existing documentation. It then presents the proposed structure, each document's responsibility, potential shared information, and any inconsistencies found.
No files should be modified before the plan is approved.
Second phase — implementation
After approval, the agent creates or updates README.md, AGENTS.md, and .chaos/, organizes canonical information, and checks consistency between documentation, code, and contracts.
The prompt also instructs agents not to invent requirements, duplicate information, or include credentials or sensitive data. Adoption can start with a single repository and grow into shared context as needed.
Get started: CHAOS — Official repository
Adoption prompt: CHAOS Implementation Starter Prompt
Example project: CHAOS Example
Conclusion
CHAOS proposes that the knowledge needed to understand a system should be part of the system itself, in a structure accessible to humans and AI agents.
Defined entry points, canonical context, and shared information across repositories let different agents work from the same technical reference without depending on previous conversations or a specific vendor.
The agent may change. The system's context should remain accessible, consistent, and up to date.
Further reading
External sources
- AGENTS.md — Convention for agent instructions
- Architecture Decision Records (ADR)
- C4 Model — Architecture visualization
Related articles
- Context architecture, engineering, and documentation
- Memory and work continuity with AI agents
- Standardizing projects for development with AI agents
- Harnesses, skills, tools, and MCP
- Protecting context and sensitive data