104 lines
5.1 KiB
Markdown
104 lines
5.1 KiB
Markdown
 
|
# AGENTS.md — Canonical Agent Instructions
|
|||
|
|
|
|||
|
|
Canonical instruction set for any coding agent working in this repository
|
|||
|
|
(Claude Code, GPT-OSS harnesses, others). `CLAUDE.md` points here.
|
|||
|
|
This file is loaded into every session — keep it short. Process details
|
|||
|
|
live in `WORKFLOW.md`; read that when a task begins, not preemptively.
|
|||
|
|
|
|||
|
|
Tradeoff: these rules bias toward caution over speed. For trivial tasks,
|
|||
|
|
use judgment — but say so.
|
|||
|
|
|
|||
|
|
## 1. Operating Rules
|
|||
|
|
|
|||
|
|
### Think before coding
|
|||
|
|
- State your assumptions explicitly. If uncertain, ask.
|
|||
|
|
- If multiple interpretations exist, present them — don't pick silently.
|
|||
|
|
- If a simpler approach exists, say so. Push back when warranted.
|
|||
|
|
- If something is unclear, stop. Name what's confusing. Ask.
|
|||
|
|
|
|||
|
|
### Simplicity first
|
|||
|
|
- Minimum code that solves the problem. Nothing speculative.
|
|||
|
|
- No features beyond what was asked. No abstractions for single-use code.
|
|||
|
|
- No "flexibility" or "configurability" that wasn't requested.
|
|||
|
|
- No error handling for impossible scenarios.
|
|||
|
|
- If you write 200 lines and it could be 50, rewrite it.
|
|||
|
|
- Test: "Would a senior engineer call this overcomplicated?" If yes, simplify.
|
|||
|
|
- Before writing new code, stop at the first rung that holds:
|
|||
|
|
needed at all? → codebase already has it? → stdlib? → platform-native?
|
|||
|
|
→ installed dependency? → one line? → only then: the minimum that works.
|
|||
|
|
(Ladder after ponytail, MIT.)
|
|||
|
|
- Never cut, at any rung: trust-boundary validation, data-loss handling,
|
|||
|
|
security, accessibility.
|
|||
|
|
- Lazy about the solution, never about reading the code first.
|
|||
|
|
|
|||
|
|
### Surgical changes
|
|||
|
|
- Touch only what you must. Match existing style, even if you'd differ.
|
|||
|
|
- Don't "improve" adjacent code, comments, or formatting.
|
|||
|
|
- Don't refactor things that aren't broken.
|
|||
|
|
- If you notice unrelated dead code, mention it — don't delete it.
|
|||
|
|
- Remove imports/variables/functions that YOUR changes made unused;
|
|||
|
|
leave pre-existing dead code alone unless asked.
|
|||
|
|
- Every changed line must trace directly to the request.
|
|||
|
|
|
|||
|
|
### Goal-driven execution
|
|||
|
|
- Transform tasks into verifiable goals:
|
|||
|
|
"fix the bug" → "write a test that reproduces it, then make it pass".
|
|||
|
|
- For multi-step work, state a brief plan: step → verify, step → verify.
|
|||
|
|
- A task is well-defined only if it names all four:
|
|||
|
|
**files, action, verify, done.** Missing one? The task is too vague — say so.
|
|||
|
|
|
|||
|
|
### Verification before completion
|
|||
|
|
- Never claim something works without evidence: a test run, command
|
|||
|
|
output, a rendered result. "Should work" is not a status.
|
|||
|
|
- Report every task/slice with exactly one status:
|
|||
|
|
`DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`.
|
|||
|
|
- Uncertainty is reported, never swallowed. Flag your shakiest calls.
|
|||
|
|
|
|||
|
|
## 2. Project Initialization (Gate 0)
|
|||
|
|
|
|||
|
|
At session start, read `PROJECT.md`. If it does not exist, initialization
|
|||
|
|
is your first task: before anything else, ask the Gate 0 questions defined
|
|||
|
|
in `WORKFLOW.md` — response language, size-S gate exception (yes/no),
|
|||
|
|
one-line project purpose, audience — write the answers to `PROJECT.md`,
|
|||
|
|
and have `validate.py` accept it. Never guess these answers; ask.
|
|||
|
|
|
|||
|
|
## 3. Workflow
|
|||
|
|
|
|||
|
|
For anything beyond a trivial change, read `WORKFLOW.md` and follow its
|
|||
|
|
gates. At task start, propose a size class (S/M/L); the human confirms
|
|||
|
|
(possibly batched later). **Never advance past a gate without explicit
|
|||
|
|
human approval** — sole exception: size-S tasks, and only if `PROJECT.md`
|
|||
|
|
explicitly grants that exception.
|
|||
|
|
|
|||
|
|
## 4. Repository Map
|
|||
|
|
|
|||
|
|
| Path | Purpose |
|
|||
|
|
|---|---|
|
|||
|
|
| `WORKFLOW.md` | Gate 0 (init) + Gates 1–5, size classes, debugging path, session handoff, refinement ritual |
|
|||
|
|
| `PROJECT.md` | Per-project answers from Gate 0: language, size-S exception, purpose, audience |
|
|||
|
|
| `STATUS.md` | Generated overview: open issues, active designs, recent ADRs — do not edit by hand |
|
|||
|
|
| `schema.yaml` | Frontmatter schema — single source of truth for artifact structure |
|
|||
|
|
| `docs/adr/` | Architecture Decision Records — binding; never edited, only superseded |
|
|||
|
|
| `docs/design/` | One design doc per undertaking; completed ones move to `done/` |
|
|||
|
|
| `docs/aar/` | Standalone After Action Reviews (incidents, major deviations only) |
|
|||
|
|
| `docs/issues/` | In-repo issues, one file each; status lives in frontmatter |
|
|||
|
|
| `docs/wiki/` | Wiki areas as folders, created on demand — rules in `docs/wiki/index.md` |
|
|||
|
|
| `docs/sources/` | Immutable original sources; wiki pages cite them — read-only for agents |
|
|||
|
|
| `scripts/` | Deterministic tooling: `validate.py`, `gen_status.py` |
|
|||
|
|
|
|||
|
|
Before proposing options (Gate 2), read the relevant ADRs and AARs first —
|
|||
|
|
past decisions and learnings are input, not trivia.
|
|||
|
|
|
|||
|
|
## 5. Artifact Rules
|
|||
|
|
|
|||
|
|
- All artifacts are standard Markdown with YAML frontmatter conforming to
|
|||
|
|
`schema.yaml`. Standard links only (`[text](path.md)`), no wikilinks.
|
|||
|
|
Diagrams as Mermaid. This keeps every artifact portable across LLMs,
|
|||
|
|
GitLab, and Obsidian.
|
|||
|
|
- Never invent frontmatter fields or status values. `validate.py` is
|
|||
|
|
authoritative; if it rejects your artifact, fix the artifact, not the
|
|||
|
|
validator.
|
|||
|
|
- Deterministic jobs (status generation, validation, link checks) are done
|
|||
|
|
by scripts, not by you. If a deterministic job lacks a script, propose
|
|||
|
|
one instead of doing it by inference.
|