diff --git a/docs/agent-scale-principles.md b/docs/agent-scale-principles.md new file mode 100644 index 0000000..377e82b --- /dev/null +++ b/docs/agent-scale-principles.md @@ -0,0 +1,38 @@ +# Agent-scale principles (from Anthropic's Scion writeup, applied here) + +*Source: anthropic.com/engineering/redesigning-source-control. What follows is only +what transfers to this troupe — a small, zero-cost agent collective on git — not a +summary of their system. Scion itself is explicitly not for us (it exists for 30k-merge/ +day monorepos; Anthropic says so). We keep git + Gitea.* + +1. **Review intent, not lines.** The principal/operator reviews *why* a change exists and + whether it violates a standing constraint — not every line. Line-by-line review is a + human-scale habit that doesn't scale to agents. (Anthropic: "examine the intent of the + change as opposed to reading every line of code.") + +2. **Say "no" to over-engineering.** Agents over-defend against hypothetical concerns and + take brute-force shortcuts that violate system constraints — inventing identifiers + instead of marking them `unverified`, re-scanning the commit log instead of asking the + record. The operator's highest-value act is steering these away. This is why Gemini's + fabricated `fleet-ops`/`self_heal.py` example IDs were recorded as a fault, not waved + through as harmless placeholders. + +3. **Post-merge verification beats a merge queue.** A global lock/queue doesn't make sense + when many agents land work concurrently. Let changes land, then verify after the fact. + This troupe already works this way — the operating partner re-runs claims from the host + and records faults (corrected, not deleted). Formalize it; don't gate on locks. + +4. **Concurrent changes conflict — agents fix them fast.** Don't build ceremony around + avoiding conflicts; build the habit of resolving them in the open and recording what + happened. (Anthropic: "Claude can fix these conflicts faster than humans can identify + them.") + +5. **A small team + agents builds substantial systems fast.** Seven humans built a whole + VCS plus a review tool in five months. This troupe's lane model is the same shape: + many small free agents, one operator, fast landed artifacts. The limit is evidence, + not headcount. + +6. **Component "superfans."** A dedicated agent obsessively watching one component's + health catches subtle, novel failures that threshold alerts miss. Candidate lanes here: + a troupe-pipe superfan (checks every check-in/commit/reply against the evidence law) + and a forge superfan (Gitea health). Open proposal, not yet staffed.