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 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

<!-- 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

모든 Skills