Parallel agents
Merge conflicts among parallel agents concentrate in hub files: the files every
feature must touch regardless of what the feature is (the subcommand
dispatcher, the router, the single test main, the root AGENTS.md). Four rules
reduce them, in the order you usually need them:
- New behavior gets its own file. The shared file it plugs into grows by
exactly one line: a
mod declaration, a route registration, a delegating
match arm, a table entry.
- Shape edits to shared files so git merges them alone. One item per
line, stable insertion order, no drive-by rewrites of lines you did not
need to change, and never hand-resolve a generated file or lockfile;
regenerate it.
- Find and split existing hubs. Rank files by churn times size, keep only
the ones touched by unrelated features, and split them along concern seams
as pure-move commits.
- Docs hold scars and invariants, nothing else. Delete anything an agent
can discover with one grep or
--help, and shard per-module detail out of
the root doc.
References
Read the file that matches the task. Each stands alone.
references/one-feature-one-file.md: where new behavior lives, how to
recognize a hub, patterns by project shape (CLI, HTTP service, web UI,
tests).references/mergeable-edits.md: list and registry discipline, formatter
scope, ownership rules, generated files, resolving a conflict in a hub.references/hotspot-audit.md: the churn measurement command, hub vs hot
concern vs generated triage, pure-move splits, timing and cadence.references/doc-gardening.md: what AGENTS.md/CLAUDE.md and user docs are
for, the discoverability test, pruning, sharding the root doc.
1---2name: parallel-agents3description: Use when parallel agents share a codebase: adding new behavior, editing or resolving conflicts in shared files (dispatchers, registries, lockfiles), finding and splitting churn hotspots, or writing AGENTS.md, CLAUDE.md, or README.4---5
6# Parallel agents
7
8Merge conflicts among parallel agents concentrate in hub files: the files every
9feature must touch regardless of what the feature is (the subcommand
10dispatcher, the router, the single test main, the root AGENTS.md). Four rules
11reduce them, in the order you usually need them:
12
131. **New behavior gets its own file.** The shared file it plugs into grows by
14 exactly one line: a `mod` declaration, a route registration, a delegating
15 match arm, a table entry.
162. **Shape edits to shared files so git merges them alone.** One item per
17 line, stable insertion order, no drive-by rewrites of lines you did not
18 need to change, and never hand-resolve a generated file or lockfile;
19 regenerate it.
203. **Find and split existing hubs.** Rank files by churn times size, keep only
21 the ones touched by unrelated features, and split them along concern seams
22 as pure-move commits.
234. **Docs hold scars and invariants, nothing else.** Delete anything an agent
24 can discover with one grep or `--help`, and shard per-module detail out of
25 the root doc.
26
27## References
28
29Read the file that matches the task. Each stands alone.
30
31- `references/one-feature-one-file.md`: where new behavior lives, how to
32 recognize a hub, patterns by project shape (CLI, HTTP service, web UI,
33 tests).
34- `references/mergeable-edits.md`: list and registry discipline, formatter
35 scope, ownership rules, generated files, resolving a conflict in a hub.
36- `references/hotspot-audit.md`: the churn measurement command, hub vs hot
37 concern vs generated triage, pure-move splits, timing and cadence.
38- `references/doc-gardening.md`: what AGENTS.md/CLAUDE.md and user docs are
39 for, the discoverability test, pruning, sharding the root doc.
aiskillstore