docs: scaffold agent instruction tree
Add AGENTS.md, CLAUDE.md, and the agents-docs/ tree (workflow, lessons, engineering standards, context map, ADR seed, feature template) plus a domain-bearing CONTEXT.md for each of the six subdomains: toju-app, electron, server, e2e, website, docs-site. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
81
agents-docs/AGENTS_CONTEXT.md
Normal file
81
agents-docs/AGENTS_CONTEXT.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# Agent Instructions: CONTEXT.md & CONTEXT-MAP.md
|
||||
|
||||
Domain documentation lives in **`CONTEXT.md`** files co-located with the code they describe:
|
||||
|
||||
- **Single-context repo:** one `CONTEXT.md` at the root (or at the top of the single subdomain).
|
||||
- **Multi-context repo:** one `CONTEXT.md` per subdomain (e.g. `src/CONTEXT.md`, `frontend/CONTEXT.md`), indexed by `agents-docs/CONTEXT-MAP.md`.
|
||||
|
||||
This document defines how agents must detect, document, and maintain domain knowledge as the codebase grows.
|
||||
|
||||
> This file is part of the agent instruction infrastructure.
|
||||
> Do NOT create, delete, or modify this file unless explicitly instructed.
|
||||
|
||||
---
|
||||
|
||||
## What `CONTEXT.md` is for
|
||||
|
||||
A subdomain's `CONTEXT.md` is a **domain artefact**, not an agent-rule file. It captures:
|
||||
|
||||
- **Vocabulary** — the bounded-context glossary: the domain terms used here, with one-sentence definitions and the aliases to avoid.
|
||||
- **Relationships** — how the domain terms connect (cardinality, ownership).
|
||||
- **Boundaries / IO** — what this subdomain exposes externally and consumes from other subdomains.
|
||||
- **Invariants** — rules that always hold within this subdomain.
|
||||
- **Flagged ambiguities** — terms still in dispute, with proposed resolutions.
|
||||
|
||||
Agent-procedural rules (TDD, typecheck, formatter) live in `/AGENTS.md` and `agents-docs/ENGINEERING.md` — never in `CONTEXT.md`.
|
||||
|
||||
Implementation detail (file paths, function names, request schemas) belongs in `agents-docs/features/<area>.md` — never in `CONTEXT.md`.
|
||||
|
||||
## What `CONTEXT-MAP.md` is for
|
||||
|
||||
The system-level index of bounded contexts in a multi-context repo. One row per subdomain — name, one-line purpose, public surface, link to its `CONTEXT.md`. Plus relationships between contexts (upstream/downstream, shared types, events).
|
||||
|
||||
Only exists when ≥2 subdomains have their own `CONTEXT.md`. Single-context repos skip it.
|
||||
|
||||
---
|
||||
|
||||
## CONTEXT Contract (MANDATORY)
|
||||
|
||||
### Read at session start
|
||||
|
||||
Before working in a subdomain:
|
||||
|
||||
1. Read that subdomain's `CONTEXT.md`. If `agents-docs/CONTEXT-MAP.md` exists, start there to locate the right one.
|
||||
2. If your change couples two subdomains (shared types, cross-context events), read both `CONTEXT.md`s.
|
||||
3. Skip files that don't exist. **Proceed silently** — don't flag absence; producer triggers create them lazily.
|
||||
|
||||
### Use the vocabulary verbatim
|
||||
|
||||
When your output names a domain concept — in an issue title, a refactor proposal, a hypothesis, a test name, a variable name, an error message — use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
|
||||
|
||||
### Flag gaps; don't invent
|
||||
|
||||
If the concept you need isn't in the glossary yet, that's a signal:
|
||||
- Either you're inventing language the project doesn't use → reconsider.
|
||||
- Or there's a real gap → add it (see triggers below). Don't silently coin a new term.
|
||||
|
||||
### Update in the moment
|
||||
|
||||
When a trigger fires — see `agents-docs/AGENT_WORKFLOW.md` § 4 CONTEXT.md upkeep for the canonical trigger list — update the relevant `CONTEXT.md` in the same turn, before reporting work done. The triggers cover term resolutions, user corrections to terminology, new concepts introduced by features, and self-caught synonym invention.
|
||||
|
||||
### Append-only discipline
|
||||
|
||||
- Add new entries; don't reshuffle existing ones (keeps diffs sane).
|
||||
- If a term changes meaning, supersede it with a clarifying entry — don't silently rewrite history.
|
||||
- If `Flagged ambiguities` gets resolved, move the resolution into the main vocabulary table and remove the flag.
|
||||
|
||||
### Multi-context: keep the map current
|
||||
|
||||
When adding a new subdomain `CONTEXT.md`, add a row to `agents-docs/CONTEXT-MAP.md` in the same task. When the public surface or upstream/downstream relationships change, update the map.
|
||||
|
||||
---
|
||||
|
||||
## Format
|
||||
|
||||
The format of an entry is documented at the top of each `CONTEXT.md` so it self-describes. Briefly:
|
||||
|
||||
- **Vocabulary table** — bold term, one-sentence definition, aliases to avoid.
|
||||
- **Relationships** — bullet list using bold terms and cardinality ("A **TermA** belongs to exactly one **TermB**").
|
||||
- **Boundaries / IO** — `Exposes:` and `Consumes:` bullets.
|
||||
- **Invariants** — bullet list of constraints that always hold.
|
||||
- **Flagged ambiguities** — terms still in dispute, with proposed resolutions.
|
||||
Reference in New Issue
Block a user