54 lines
3.9 KiB
Markdown
54 lines
3.9 KiB
Markdown
---
|
|
status: resolved
|
|
parent: "[[038-implement-skill-map]]"
|
|
claimed-by: "019fbb66-80d0-7a01-8ac9-01255adfc7b2"
|
|
claimed-at: "2026-08-01T00:00:00-04:00"
|
|
blocked-by: []
|
|
tags:
|
|
- ticket/research
|
|
---
|
|
|
|
# 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.
|