# AGENTS.md

This document defines how AI agents should work in this repository.

Agents must follow these conventions when reading, modifying, or generating code.

---

# 1. Project Structure

Repository layout:

project/
├ README.md
├ AGENTS.md
├ docs/
│   ├ design/          # architecture and system design
│   ├ implementation/  # technical implementation notes
│   ├ research/        # experiments and investigations
│   ├ reference/       # API references and external resources
│   └ user/            # end-user documentation
│
├ src/                 # main source code
├ tests/               # automated tests
├ scripts/             # automation scripts
├ postmortem/          # incident reports and retrospectives
└ examples/            # usage examples

Agents must preserve this structure.

---

# 2. Development Workflow

Agents must follow this workflow when implementing features.

1. Read relevant documents in:

docs/design
docs/implementation

2. Implement code inside:

src/

3. Add or update tests inside:

tests/

4. Update documentation when necessary.

---

# 3. Coding Rules

Agents must follow these rules:

- Do not introduce new frameworks without justification
- Keep functions small and composable
- Prefer readability over cleverness
- Avoid duplication

When modifying code:

- Prefer editing existing modules over creating new ones
- Follow existing naming conventions

When building features, build a tiny, end-to-end slice of the feature first, seek feedback, then expand out from there.
Tracer bullets comes from the Pragmatic Programmer. When building systems, you want to write code that gets you feedback as quickly as possible. Tracer bullets are small slices of functionality that go through all layers of the system, allowing you to test and validate your approach early. This helps in identifying potential issues and ensures that the overall architecture is sound before investing significant time in development.

---

# 4. Testing Requirements

All new features must include tests.

Tests must be placed in:

tests/

Test guidelines:

- Prefer unit tests
- Add integration tests for workflows
- Tests must be deterministic
- Avoid external dependencies

Agents must run tests before finishing a task.

---

# 5. Documentation Rules

Documentation must be updated when:

- architecture changes
- APIs change
- new workflows are added

Docs location rules:

Architecture → docs/design  
Implementation detail → docs/implementation  
User documentation → docs/user  

---

# 6. Examples

When introducing new APIs or workflows, agents must add examples in:

examples/

Examples must be runnable.

---

# 7. Scripts

Automation scripts go into:

scripts/

Examples:

build
deploy
test
data migration

Scripts should be idempotent.

---

# 8. Postmortems

When bugs or incidents occur, create a report in:

postmortem/

Postmortem format:

incident.md

Include:

- what happened
- root cause
- fix
- prevention

Agents may reference postmortems to avoid repeating past mistakes.

---

# 9. Safety Rules

Agents must NOT:

- delete large sections of code without reason
- change project structure
- modify dependencies without explanation

When unsure, agents should request clarification.

---

# 10. Pull Requests

Agent-generated changes must:

- pass tests
- follow coding conventions
- include documentation if required

---

# 11. Communication and Explanation

Make outputs easy for the user to understand and review. As agents do more work autonomously, support the user's oversight with clear explanations.

Use a writing style inspired by ASD-STE100 Simplified Technical English, aiming for roughly 80% adherence when strict rules would make the explanation awkward:

- Use plain words, short sentences, and active voice.
- Express one idea per sentence and use terms consistently.
- Keep explanations concise while preserving necessary detail.

Choose the output format that best helps the user understand the topic:

- Text for direct answers and simple instructions.
- Diagrams or images for relationships, structure, and flows.
- Interactive HTML pages for exploring complex topics, comparisons, or changing scenarios.
- Custom explainer videos with visual demonstrations and narration when they would help explain a topic. Use available narration tools or local alternatives as appropriate.

Create custom, disposable explanatory artifacts when they improve understanding. Match the effort and format to the task; simple answers can stay simple.

Source: [Andrej Karpathy on understanding LLM outputs](https://x.com/karpathy/status/2105819303471976479).