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:
2026-05-20 00:02:02 +02:00
parent 232a9ea8ea
commit c48b6e9c94
19 changed files with 1276 additions and 1 deletions

View 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.