danmcinerney/architect-loop

codebase-design

Shared vocabulary for designing deep modules and for naming factory concepts consistently.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/danmcinerney/architect-loop --skill codebase-design

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

<!-- Adapted from mattpocock/skills (MIT). -->

Codebase Design

Design deep modules: a lot of behavior behind a small interface, placed at a clean seam, testable through that interface. Use this language wherever code or a factory issue is being designed. The aim is leverage for callers, locality for maintainers, and testability for everyone.

Glossary

Use these terms exactly — don't substitute component, service, boundary, or API when you mean module or interface; don't say task or ticket for issue, or test file for frozen check. Consistent language is the whole point.

Design (Pocock, adapted):

  • Module - anything with an interface and an implementation, at any scale: a function, a package, or a whole vertical slice.
  • Interface - everything a caller must know to use a module correctly: types, invariants, ordering, error modes, config, performance - not just a signature.
  • Implementation - the body of code behind the interface; distinct from adapter, which names role at a seam, not substance.
  • Depth - leverage at the interface: behavior reached per unit of interface learned. Deep means a small interface over a big implementation; shallow is the opposite, and to avoid.
  • Seam (Feathers) - the place a module's interface lives; where behavior can change without editing there.
  • Adapter - a concrete thing satisfying an interface at a seam. One adapter is a hypothetical seam; two make it real.
  • Leverage - what callers get from depth: one implementation pays off across many call sites and tests.
  • Locality - what maintainers get from depth: change and bugs concentrate in one place instead of spreading.

Factory (one line each; matches `docs/spec/skill-library.md` Target flow):

  • Run - one factory build from intake to the closing PR, on its own factory branch.
  • Tracking issue - the run's parent issue: dashboard, digest, preflight record.
  • Issue - one vertical-slice unit of work: one builder job, one disjoint file set, one change-skeleton.
  • Slice - the vertical cut an issue implements; slice names the cut, issue names its tracker record - same unit, two angles.
  • Frozen check - the committed, read-only acceptance check a builder's work is graded against.
  • Check-runner - the deterministic script that grades a frozen check's RUN items and exits typed (0/2/5).
  • Strategist - the fresh high-judgment subagent that drafts specs, cuts issues, stress-tests plans, and runs full-lane reviews.
  • Builder - the fresh, worktree-isolated agent that implements one issue and never commits.
  • Orchestrator - the one session that grounds, dispatches strategist and builder work, freezes, and integrates; never writes implementation code; in the fast lane (/architect-fast) it also runs the closing test pass whose output feeds the builder review - a recorded relaxation.
  • Factory branch - the run's integration branch (factory/<run>) that job branches merge into.
  • Worktree - the isolated git checkout a builder or reviewer works in, verified against the freeze commit.
  • Job report - a builder's raw-evidence artifact, ending in one STATUS line.
  • Verdict - the grading record posted on an issue at close: checkrun summary plus typed exit, postflight result, slice call, decisive reason; the closing review's run-level verdict goes on the tracking issue.
  • Ruling - an orchestrator decision recorded post-freeze: a PHASE-0 execution conflict, boundary amendment, or respawn answer.
  • Digest - the shipped-issues, diffstat, rulings, and domain-language summary handed to the integrate subagent's docs pass.
  • Hard stop - an irreversible or destructive action the loop refuses without a human ruling.

Deep vs. shallow

A deep module hides a lot of implementation behind a small interface: few methods, simple params, most of the complexity out of sight. A shallow module is the opposite - an interface almost as complex as what it wraps, often a near-passthrough. When shaping an interface, ask whether the method count and params can shrink, and whether more logic can move inside.

Principles

  • Depth is a property of the interface, not the implementation - a deep

module can be built from small internal seams its own tests use, without exposing them at the external interface.

  • The deletion test: imagine deleting the module. If complexity vanishes,

it was a pass-through; if it reappears across N callers, it was earning its keep.

  • The interface is the test surface - callers and tests cross the same

seam. If you want to test past the interface, the module is probably the wrong shape.

  • One adapter means a hypothetical seam; two adapters means a real one.

Don't introduce a seam unless something actually varies across it.

Designing for testability

  • Accept dependencies, don't create them - a function that takes its

gateway is testable; one that builds a StripeGateway() internally is not.

  • Return results, don't produce side effects - a function that returns a

computed discount is testable; one that mutates a cart in place is not.

  • Small surface area: fewer methods = fewer tests needed; fewer params =

simpler test setup.

Going deeper

  • Deepening a cluster given its dependencies - see DEEPENING.md:

dependency categories, seam discipline, and replace-don't-layer testing.

  • Exploring alternative interfaces - see DESIGN-IT-TWICE.md: dispatch

parallel subagents to design the interface several radically different ways, then compare on depth, locality, and seam placement.

同じリポジトリから

関連する Skills

すべての Skills