For small, high-context teams relying on triad pairing and designer-owned CLI substrates, how can we structure the context bridge (glossaries, boundary maps, example flows) so that juniors are forced to exercise their own judgment—e.g., by explaining or editing agent proposals—rather than just routing work through agents, and what review patterns would show that this is actually slowing apprenticeship decay instead of adding busywork?
dhh-agent-first-software-craft | Updated at
Answer
Use the context bridge as a teaching surface, then verify with review patterns and lightweight metrics.
- Context-bridge structure that forces judgment
A. Glossaries as prompts for explanation
- Each domain term gets:
- 1–2 line definition.
- 1–2 “gotchas” or tradeoffs.
- 1 worked example (call site, CLI flow).
- Junior rule in triads:
- Before accepting an agent diff touching a glossary term, they must:
- Point to the term.
- Explain in 1–2 sentences how the change fits or violates it.
- If it violates, propose a glossary tweak or a diff edit.
- Before accepting an agent diff touching a glossary term, they must:
- Harness support:
cb:explain-term <Term> <diff-file>opens term + asks junior: “Does this change respect the gotchas? Answer before continue.”
B. Boundary maps with “what crosses here?” questions
- Keep a simple map per boundary:
- Responsibilities.
- Allowed dependencies.
- 1–3 examples of good/ bad crossings.
- Junior rule:
- Any diff that changes calls across a boundary must include a 2–3 line “boundary note” in the PR:
- Old call pattern.
- New call pattern.
- Why this still fits the boundary description.
- Any diff that changes calls across a boundary must include a 2–3 line “boundary note” in the PR:
- Harness command:
cb:boundary-note <boundary-name> <diff>pre-fills old/new edges and prompts the junior to justify them.
C. Example flows as “edit, don’t just run” templates
- Keep a small set of CLI flows per domain:
- Happy path.
- One edge case.
- One failure/rollback.
- Junior rule:
- When using an agent to extend a flow, they must:
- Copy an existing example flow.
- Edit it by hand first (parameters, steps, checks).
- Only then ask the agent to fill in boilerplate.
- When using an agent to extend a flow, they must:
- Harness:
cb:new-flow-from <example>opens a copy in editor, disables auto-run until a human edit is detected.
D. Triad pairing rituals
- Before merging an agent-produced diff:
- Junior walks senior + designer through:
- Which glossary terms apply.
- Which boundaries were touched and why that’s OK.
- Which example flow they used or had to extend.
- Senior reviews the explanation as much as the code.
- Junior walks senior + designer through:
- Review patterns that indicate reduced apprenticeship decay
A. Explanation-first PRs
- PR template sections:
- “Key terms used and why.”
- “Boundary touched and justification.”
- “Example flow used/updated.”
- Pattern to look for over time:
- Junior-authored sections become:
- Shorter, clearer.
- More often correcting agent suggestions rather than rubber-stamping.
- Junior-authored sections become:
B. Diff-focused, not prompt-focused, conversations
- In review threads:
- Healthy signal: comments reference code, boundaries, and flows (“This leaks Billing into Projects”) more than prompts (“ask the agent to try X”).
- Track a small sample monthly to see if the ratio of “code/boundary comments” to “prompt-fix comments” rises for junior PRs.
C. Junior challenge rate
- Log a simple tag in reviews when a junior:
- Rejects an agent proposal and proposes an alternative.
- Edits an agent-generated boundary or flow.
- Over quarters, you want:
- Challenge rate per junior increasing, then stabilizing.
- No big drop when delivery pressure spikes.
D. Review time profile
- For junior-heavy diffs:
- Time split should move toward:
- Less time fixing obvious mistakes agents could avoid with better prompts.
- More time on higher-order questions (boundary shape, UX–code fit).
- Time split should move toward:
- A simple pulse: reviewers label each review “mostly syntax/implementation” vs “mostly boundary/behavior.” You want the latter share to grow without incident rates rising.
- How to avoid busywork
- Keep artifacts small:
- Glossary entries 3–6 lines max.
- Boundary maps 1 screen each.
- Only 1–3 example flows per domain.
- Automate retrieval:
- Harness auto-links relevant terms/boundaries/flows in PRs and triad sessions; juniors don’t hunt docs.
- Tie rituals to real gates:
- No merge for boundary-touching diffs without a boundary note.
- No new flows without linking to an example.
- Retire dead scaffolding:
- Quarterly: prune unused glossary terms/flows.
- Drop any question from templates that reviewers skip or never comment on.
- What to actually measure
- For each junior over time:
-
of diffs where they authored boundary notes or glossary edits.
-
of agent proposals they rejected/rewrote.
- Defect/rollback rate of their changes.
-
- Healthy pattern:
- More authored notes and rejections.
- Flat or improving defect rates.
- Reviewer time per junior diff not exploding.
If these curves move in that direction and review threads stay about behavior and boundaries instead of prompts and harness quirks, the context bridge is likely slowing apprenticeship decay instead of adding ceremony.