Keep the personal half of the desktop in one place, and ask before installing it
Agent instructions, skills, SSH host aliases and expansion triggers are worth having identical on every machine one person owns, and belong in none of the shared configuration. They live in user/ now, with a manifest saying where each piece goes and a link-user stage that puts it there. That stage does nothing unless the machine said yes. Somebody who clones Panama to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was; the question names the destinations and defaults to no. Anything displaced goes to config/old rather than being deleted. ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one file, which is the drift this exists to prevent. Also adds the vitals toggles for the battery and Claude usage readouts, which had preferences and no way to reach them.
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
# Design It Twice
|
||||
|
||||
Explore several interfaces for one module in parallel, because the first idea is unlikely to be the
|
||||
best. Uses the vocabulary in [SKILL.md](SKILL.md): **module**, **interface**, **seam**, **adapter**,
|
||||
**leverage**.
|
||||
|
||||
## Gate: is this worth the ceremony?
|
||||
|
||||
This pattern spends several agents on one decision. It earns that only where the solution space is
|
||||
genuinely wide and the choice is expensive to reverse:
|
||||
|
||||
- **Run it when** the module is load-bearing, several plausibly-good interfaces exist, and callers
|
||||
will be written against whichever one wins.
|
||||
- **Skip it when** one obvious interface fits, the module is small, or the decision is cheap to
|
||||
change later. Design it once, in this context window, and move on.
|
||||
|
||||
A single agent that finishes the job in one pass should just finish it. Reach for the fan-out for
|
||||
breadth, not for routine work.
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Frame the problem space
|
||||
|
||||
Before spawning anything, write a user-facing explanation of the problem space:
|
||||
|
||||
- The constraints any new interface must satisfy
|
||||
- The dependencies it relies on, and their category from [DEEPENING.md](DEEPENING.md)
|
||||
- A rough code sketch to make the constraints concrete. This grounds the discussion; it is not a
|
||||
proposal.
|
||||
|
||||
Show it, then proceed immediately. The reading happens while the agents work.
|
||||
|
||||
### 2. Spawn the designers
|
||||
|
||||
Spawn three or more agents in parallel, each producing a **radically different** interface. Give each
|
||||
a separate technical brief (file paths, coupling details, dependency category, what sits behind the
|
||||
seam) and a different design constraint:
|
||||
|
||||
| Agent | Constraint |
|
||||
|---|---|
|
||||
| 1 | Minimise the interface: one to three entry points, maximum leverage per entry point |
|
||||
| 2 | Maximise flexibility: support many use cases and extension |
|
||||
| 3 | Optimise for the most common caller: make the default case trivial |
|
||||
| 4 (where relevant) | Design around ports and adapters for cross-seam dependencies |
|
||||
|
||||
**These agents design, they do not write.** Each returns a proposal; none edits a file, so there is
|
||||
no file ownership to divide and no chance of a collision. Say so in each brief.
|
||||
|
||||
Include both the [SKILL.md](SKILL.md) vocabulary and the project's `CONTEXT.md` vocabulary in every
|
||||
brief, so the proposals name things consistently and can actually be compared.
|
||||
|
||||
Each agent returns:
|
||||
|
||||
1. The interface: types, entry points, params, plus invariants, ordering, and error modes
|
||||
2. A usage example showing how callers use it
|
||||
3. What the implementation hides behind the seam
|
||||
4. Its dependency strategy and adapters
|
||||
5. Trade-offs: where leverage is high, where it is thin
|
||||
|
||||
### 3. Present and compare
|
||||
|
||||
Present the designs one at a time so each can be absorbed, then compare them in prose along
|
||||
**depth** (leverage at the interface), **locality** (where change concentrates), and **seam
|
||||
placement**.
|
||||
|
||||
Finish with your own recommendation: which design is strongest and why. Where elements from different
|
||||
designs combine well, propose the hybrid. Be opinionated. The point of the fan-out is a strong read,
|
||||
not a menu.
|
||||
Reference in New Issue
Block a user