128 lines
4.8 KiB
Markdown
128 lines
4.8 KiB
Markdown
# 08 — How we work
|
|
|
|
`AGENTS.md` D17. Pouya architects. Claude Code implements, then adversarially
|
|
reviews its own work. This is a standing agreement encoded in the repository, so
|
|
it does not need restating in every prompt.
|
|
|
|
---
|
|
|
|
## The short version
|
|
|
|
```
|
|
/build the /med-arb/ page
|
|
```
|
|
|
|
That single command runs: plan → implement → adversarial review → resolve →
|
|
verify → record. It requests deep reasoning, reads `AGENTS.md` and the specs,
|
|
stops if the task conflicts with a locked decision, invokes two independent
|
|
reviewers on the finished diff, resolves what they find, runs the checks, and
|
|
appends the Change Log entry.
|
|
|
|
You do not need to ask for thinking, for review, or for the record to be updated.
|
|
Those are the agreement, not the request.
|
|
|
|
## The three commands
|
|
|
|
| Command | Does |
|
|
|---|---|
|
|
| `/build <task>` | The full loop. Use for every substantive change |
|
|
| `/review [scope]` | The review pass alone, on the working tree or a named scope. Reports; fixes nothing without your say-so |
|
|
| `/wrap` | End of session — updates `AGENTS.md` under its constitution and leaves the tree clean |
|
|
|
|
## The two reviewers
|
|
|
|
Both are defined in `.claude/agents/` and run in parallel on the diff.
|
|
|
|
**`adversarial-reviewer`** reads the code: correctness and edge cases,
|
|
accessibility, crawlability, performance budgets, security, and whether a
|
|
materially simpler correct version exists.
|
|
|
|
**`claims-auditor`** reads the copy against `AGENTS.md` §4 and nothing else. It
|
|
extracts every factual assertion — credentials, roles, numbers, languages,
|
|
locations, capabilities, and the JSON-LD — and traces each to the Verified table.
|
|
Anything untraceable is reported and does not ship.
|
|
|
|
It is a separate agent on purpose. A general-purpose reviewer will happily
|
|
approve elegant code containing a claim that should never have been published,
|
|
because professional-conduct compliance is not what it is looking at. On this
|
|
project that is the highest-stakes failure mode, so it gets its own pass.
|
|
|
|
**Both are instructed to treat uncertainty as a defect.** They will sometimes be
|
|
wrong. That is the intended trade: explaining why a finding is mistaken costs
|
|
minutes, and a missed defect on a licensed professional's public marketing page
|
|
costs a great deal more.
|
|
|
|
## The rule that makes it work
|
|
|
|
**The reviewers are given the diff and the specs — never the implementer's
|
|
explanation of why the work is correct.**
|
|
|
|
A rationale anchors the reviewer. Told why something is right, a reviewer looks
|
|
for confirmation and finds it; given only the artefact, it forms an independent
|
|
view. That independence is the entire mechanism. Every other detail of this
|
|
protocol is adjustable. This one is not.
|
|
|
|
---
|
|
|
|
## Writing a task
|
|
|
|
The commands carry the process, so your prompt only needs to carry the decision.
|
|
Short and specific beats long and hedged.
|
|
|
|
**Good:**
|
|
|
|
```
|
|
/build the /med-arb/ page per docs/01-architecture.md
|
|
```
|
|
|
|
```
|
|
/build step 5 of the build order — the practice index and all six area pages
|
|
```
|
|
|
|
```
|
|
/build the intake form on /contact/, per docs/05-backend-spec.md.
|
|
Booking stays parked — reserve the slot, render nothing.
|
|
```
|
|
|
|
**When you are making a decision rather than assigning work**, say so plainly and
|
|
let it record the decision:
|
|
|
|
```
|
|
Decision: drop the /for-parties/ page. The plain-language audience can be
|
|
served by a section on /mediation/ instead. Update AGENTS.md and the
|
|
architecture spec, then tell me what else this affects.
|
|
```
|
|
|
|
**When you want an opinion before committing**, ask for one — do not ask for
|
|
code:
|
|
|
|
```
|
|
Before building /fees/: read docs/07-fees.md and tell me what a referring
|
|
lawyer would find missing from that page. Do not write anything yet.
|
|
```
|
|
|
|
## What it will do without being asked
|
|
|
|
- Stop and ask when a task conflicts with a locked decision, or needs a fact it
|
|
does not have. A blocked build is a correct build.
|
|
- Leave `TODO(pouya)` in the source and a numbered question in `AGENTS.md` §9
|
|
rather than inventing a fact or softening a claim into something defensible.
|
|
- Surface `AGENTS.md` §12 Standing Reminders at the start of a substantial
|
|
session — including R1, your standing instruction about the licensure wording.
|
|
- Refuse to publish a claim that is not in the §4 Verified register.
|
|
- Append a Change Log entry covering decisions and plans, not only code.
|
|
|
|
## What to watch for
|
|
|
|
**A review that finds nothing.** Possible, but it should be rare, and it must
|
|
list which lenses were applied and what was checked. "Looks good" is not a
|
|
review — send it back.
|
|
|
|
**Findings declined without a reason.** Declining is legitimate. Declining
|
|
silently is not; the reasoning belongs in the Change Log so a later reader can
|
|
see that judgement was exercised rather than the finding missed.
|
|
|
|
**A check reported as passing that was not run.** "Should pass" is not a result.
|
|
If a build, a Lighthouse run, or a JavaScript-disabled render was not actually
|
|
executed, it must say so.
|