How to read this
What to load, in what order, driven by the repository rather than the prompt — and what wins when two sources disagree.
This site is a strong prior, not gospel. It records what was decided and why. When the code in front of you disagrees, the code wins — and then the page gets fixed.
Precedence, when two sources disagree
| Rank | Source | Why it outranks the next |
|---|---|---|
| 1 | A direct instruction in the conversation | The person is here and can be asked |
| 2 | The repository's own CLAUDE.md / AGENTS.md | It is scoped to this codebase and its author chose it deliberately |
| 3 | The code itself | It is what actually runs |
| 4 | This site | Cross-project knowledge, true until a repository says otherwise |
| 5 | Default model behaviour | The thing this site exists to replace |
A page that loses to the code is a page to correct, not a page to ignore silently. Say which one lost.
Read once, whatever the repository is
These five do not depend on the stack, and nothing below will trigger them. They are how you work, not what you are working on.
| Page | Governs |
|---|---|
| Working agreement | The level of context assumed, and closing your own loose ends |
| Evidence and forecast | Every claim carries a pointer; every multi-step goal is priced first |
| Reporting | The work-report template, and the four modes that replace it |
| Secrets | A secret's value never reaches the transcript, whatever its source |
| Git conventions | Attribution, and never pushing unasked |
Then load on demand, driven by the repository
Do this once per session, before the first non-trivial edit. It costs two or three page reads, not a walk of the tree.
- Detect the stack from the repository, not from the prompt. Read the
manifest —
package.json,pom.xml/build.gradle,pyproject.toml,go.mod,Cargo.toml— plus the repository's ownCLAUDE.md/AGENTS.md. - Read the pages the detected stack maps to, using the table below. Two or three pages, never the whole site.
- Load more later, on demand. Touching a new area mid-task — tests, deploy, a second language — read that page then. Loading is lazy by design.
| Signal in the repository | Read |
|---|---|
| A new project, a new module, or any structural decision | Method · Architecture |
| A client project starting, or a brief being written | Artefacts |
pom.xml / build.gradle with Spring | Java · Spring Boot |
Any .java without Spring | Java |
go.mod / go.work | Go · Go services |
astro in package.json or astro.config.* | Astro |
@tanstack/react-start | TanStack Start · Feature structure |
@tanstack/react-router without react-start | Vite · Feature structure |
src/features/ in a TS/JS repository | Feature structure |
tailwindcss dependency or components.json | Tailwind and shadcn |
| Writing or fixing tests, any stack | Testing |
| Anything a person will look at or touch | Layout and spacing · Motion and polish |
railway.json or a Railway project | Railway |
| Auditing, or running a hardened multi-agent prompt | Prompts |
Rules while using it
- Check the
Verifieddate before quoting a version or an API. Older than about six months on a library detail — read the current documentation instead. - Say when a page drove a decision — "per Architecture → Hexagonal: …" — so the page can be challenged rather than the conclusion.
- No matching page? Say so in one line and proceed. Then write one if the work earned it.
- Nothing here is client-specific. If a page names a client, a product or a repository path, it is in the wrong place: generalise it or delete it.
What earns a new page
Write when something was non-obvious and will recur: a decision that took real debate or a documentation dive, a trap that cost more than about fifteen minutes, a pattern proven on a second project.
Generalise it, say why and not just what, point at proof, and add it to the loading table above in the same edit — an unreachable page is a page nobody loads.