3.9 KiB
status, parent, claimed-by, claimed-at, blocked-by, tags
| status | parent | claimed-by | claimed-at | blocked-by | tags | |
|---|---|---|---|---|---|---|
| resolved | 038-implement-skill-map | 019fbb66-80d0-7a01-8ac9-01255adfc7b2 | 2026-08-01T00:00:00-04:00 |
|
Implement workflow codebase design research
Question
What role should codebase-design have in the packaged Wayfinder-aware implementation workflow, especially for test-driven-development and review?
Findings
The old local codebase-design skill and Matt Pocock's codebase-design skill are nearly the same direct counterpart.
Both define deep-module vocabulary around module, interface, implementation, depth, seam, adapter, leverage, and locality.
Both aim to make code more testable and maintainable by placing behavior behind a small interface at a clean seam.
Sources: /home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/codebase-design/SKILL.md, https://raw.githubusercontent.com/mattpocock/skills/main/skills/engineering/codebase-design/SKILL.md.
The old local test-driven-development skill explicitly invokes /codebase-design during planning to identify deep modules and testability checks, regardless of what triggered TDD.
That makes codebase-design part of the old implementation workflow's dependency graph, not just an opportunistic extra.
Source: /home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/test-driven-development/SKILL.md.
The important testing contract is that the interface is the test surface.
Codebase-design says callers and tests cross the same seam, and if tests need to reach past the interface then the module is probably the wrong shape.
This directly supports the TDD and no-mistakes anti-slop rules against implementation-coupled tests.
Source: /home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/codebase-design/SKILL.md.
The deepening reference classifies dependencies as in-process, local-substitutable, remote-but-owned, or true external, and maps each category to a testing strategy.
This gives test-driven-development a concrete way to choose where a seam goes and what adapter or stand-in is legitimate for tests.
Source: /home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/codebase-design/DEEPENING.md.
The deepening reference also says to replace, not layer, tests when deepening shallow modules.
Old unit tests on shallow modules become waste once tests exist at the deepened module interface, and tests should assert observable outcomes through the interface rather than internal state.
This is relevant to implementation slices that include prefactoring before behavior.
Source: /home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/codebase-design/DEEPENING.md.
The design-it-twice reference is a heavier HITL or parallel-agent pattern for exploring alternative interfaces.
It is useful when a task reveals that seam placement or interface shape is a substantive design decision, but it should not become a mandatory step in every implementation slice.
Sources: /home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/codebase-design/DESIGN-IT-TWICE.md, https://raw.githubusercontent.com/mattpocock/skills/main/skills/engineering/codebase-design/DESIGN-IT-TWICE.md.
The packaged local skills repository does not currently contain a packaged codebase-design skill.
If the workflow includes a packaged test-driven-development skill that depends on codebase-design vocabulary, either codebase-design should be packaged too, or the TDD skill must inline enough of the deep-module and seam-placement contract to stand alone.
Source: /home/alexion/wrk/skills/skills.
Conclusion
Add codebase-design to the implementation workflow scope or explicitly inline its deep-module seam guidance into test-driven-development and review.
The cleaner workflow is to package codebase-design as a supporting skill because TDD, review, and implementation all need the same vocabulary for seams, interfaces, adapters, test surfaces, and prefactoring.