# Repository structures for coding agents

Choose the smallest structure that preserves the information your work needs.

## Minimal harness

```text
project/
|-- AGENTS.md
|-- PROGRESS.md
|-- feature-list.json
|-- package.json or pyproject.toml
|-- src/
`-- tests/
```

Use this for a small repository, one team, and tasks that finish within a few
sessions.

## Growing harness

```text
project/
|-- AGENTS.md
|-- PROGRESS.md
|-- docs/
|   |-- architecture.md
|   |-- product.md
|   |-- security.md
|   |-- reliability.md
|   `-- plans/
|       |-- active/
|       `-- completed/
|-- scripts/
|   |-- setup
|   `-- verify
|-- tests/
|   |-- unit/
|   |-- integration/
|   `-- e2e/
`-- src/
```

Use this when the agent needs progressive disclosure, several verification
layers, and checked-in plans.

## Multi-package harness

Keep the root `AGENTS.md` focused on repository-wide constraints. Place a local
instruction file inside a package only when its commands or rules differ.

```text
project/
|-- AGENTS.md
|-- docs/
|-- apps/
|   `-- web/
|       |-- AGENTS.md
|       `-- tests/e2e/
`-- packages/
    `-- payments/
        |-- AGENTS.md
        `-- tests/
```

Do not repeat root rules in every package. Link back to the source of truth.