improve-codebase-architecture
Architectural exploration — seam decisions, entry-module isolation, zero-dep core gate. Plan under docs/plans/. Use when improving architecture, consolidating modules, or enforcing import boundaries.
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 5
- Forks
- 0
01 前言 Front Matter
- name
- improve-codebase-architecture
- description
- Architectural exploration — seam decisions, entry-module isolation, zero-dep core gate. Plan under docs/plans/. Use when improving architecture, consolidating modules, or enforcing import boundaries.
02 资源文件 2
- 参考文档LANGUAGE.md8.8 KB
- 参考文档REFERENCE.md12.2 KB
03 SKILL.md 正文
Improve Codebase Architecture
This repo uses plan files under docs/plans/ instead of temp reports; vocabulary in LANGUAGE.md is the architecture nouns. Domain terms: docs/glossary.md (persistence language: backend, codec, source, envelope, hydration signal).
Explore a slice of the codebase (a seam, an entry point, a module cluster) like an AI would, surface architectural friction, discover opportunities for improving testability and module boundaries, and propose deepening / boundary-enforcement refactors as plan files under docs/plans/ (see Step 7).
A deep module (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the seam instead of inside.
Architecture vocabulary — read first
Use the terms in LANGUAGE.md exactly in every suggestion this skill produces — module, interface, implementation, depth, seam, adapter, leverage, locality, deletion test. Consistent vocabulary is what stops a deepening conversation from drifting into "component / service / boundary" mush. Pass the vocabulary to every sub-agent spawned in Step 5 alongside the technical brief so designs come back named consistently.
The vocabulary is separate from domain glossaries — LANGUAGE.md covers architecture nouns (module, seam); docs/glossary.md holds canonical persistence nouns (backend, codec, source, envelope, hydration signal). All belong in the same conversation.
Process
1. Explore the slice
Use a read-only explore subagent to navigate the slice naturally. Don't follow rigid heuristics — explore organically and note where you experience friction:
- Where does understanding one concept require bouncing between many small files?
- Where are modules so shallow that the interface is nearly as complex as the implementation?
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
- Where do tightly-coupled modules create integration risk in the seams between them?
- Which parts are untested, or hard to test (DOM-coupled when they could be
bun:test-fast)? - Where does a subpath entry leak its optional peer into the zero-dep core, or reach across to another entry's internals?
- Where does
src/lack a public-surface convention — internal helpers exported fromindex.tsalongside the public API? - Where is the zero-dep core gate at risk — a new import in
persist-core/hydrationpulling a peer dep value?
The friction you encounter IS the signal.
Done when: ≥3 candidates listed with cluster + dependency category.
2. Present candidates
Present a numbered list of opportunities. For each candidate, show:
- Cluster: which modules / entry points / seams are involved.
- Why they're coupled: shared types, call patterns, co-ownership of a concept, seam-crossing imports.
- Dependency category: see REFERENCE.md ("Dependency Categories"). Common cases in this repo: category 1 (in-process pure functions — most of
persist-core, codecencode/decode); category 2 (local-substitutable — in-memoryStateStoragetest doubles,HydrationSignalobserved without a real store). - Test impact: what existing
bun:test/tests-domcoverage would be replaced by boundary tests; whether a new architectural regression test (in the spirit of the zero-dep core gate test) should land alongside. - Boundary enforcement option: when relevant, the oxlint rule that would codify it — see REFERENCE.md § Boundary enforcement (this repo uses oxlint only; do not propose
eslint-plugin-boundaries).
Don't propose interfaces yet. Ask the user: "Which of these would you like to explore?"
3. User picks a candidate
4. Frame the problem space
Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
- The constraints any new interface / boundary rule would need to satisfy (existing import sites, the test surface, the published
.d.mtspublic API,docs/architecture.mdseam model). - The dependencies it would need to rely on (
StateStorage<TRaw>,StorageCodec<S, TRaw>,PersistableSource<TState>, theHydrationSignalobservation contract, thedocs/glossary.mdubiquitous language). - A rough illustrative code sketch to make the constraints concrete — this is not a proposal, just a way to ground the constraints.
Show this to the user, then immediately proceed to Step 5. The user reads and thinks about the problem while the sub-agents work in parallel.
5. Design multiple interfaces (or boundary structures)
Spawn 3+ subagents in parallel (generalPurpose is usually right; explore if read-only). Each must produce a radically different design.
Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category, what's being hidden / enforced). This brief is independent of the user-facing explanation in Step 4. Give each agent a different design constraint:
- Agent 1: "Minimize the interface — aim for 1–3 entry points max."
- Agent 2: "Maximize flexibility — support many use cases and extension (new codecs, new backends, new framework adapters)."
- Agent 3: "Optimize for the most common caller — make the default case trivial (one-line
persistSourcecomposition)." - Agent 4 (when applicable): "Design around the ports & adapters pattern for a cross-boundary dependency (a new backend that owns its transport — IndexedDB, a future remote storage)."
- Agent 4 alternate (boundary-enforcement candidate): design an oxlint
overrides[]block and post-refactorsrc/shape per REFERENCE.md § Boundary enforcement.
Each sub-agent outputs:
- Interface signature (types, methods, params) — or, for boundary candidates, the lint config + the post-refactor folder shape.
- Usage example showing how callers use it.
- What complexity it hides internally — or, for boundary candidates, which classes of import become impossible.
- Dependency strategy (how deps are handled — see REFERENCE.md).
- Trade-offs.
Present designs sequentially, then compare them in prose (need ≥3 sub-agent outputs before comparing).
After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not just a menu.
6. User picks an interface (or accepts recommendation)
If the choice between candidates is non-obvious — multiple designs survive the comparison, the user keeps asking "but what about X?", or the dependency graph between decisions isn't clear — drop into grill-with-docs before writing the plan. The grilling loop walks the decision tree branch-by-branch, surfaces hidden constraints, and writes resolved terminology back into docs/glossary.md inline. The plan file in Step 7 then captures decisions instead of options.
The deletion test (per LANGUAGE.md § Principles) is also worth re-running here: for each candidate, ask "if we deleted the new module 18 months from now, would the complexity it hides reappear across N callers, or just move?" If "just move", the deepening is a wash and you should pick a different candidate.
7. Create a plan file
The output of this skill is a plan file under docs/plans/. Pick the path based on what the refactor touches:
- Cross-cutting / any refactor (this repo is one surface):
docs/plans/<short-kebab-name>.mdusing the template in REFERENCE.md. - Roadmap entry: one line under the appropriate section in
docs/roadmap.md.
Write the plan, then share the file path(s) and any roadmap-link paths so the user can open them. Don't ask for review before writing.
Done when: plan file at path; roadmap link.
If the user explicitly asks for a GitHub issue, draft the issue body but do not create it directly — the user files it themselves.
Plan-file conventions: REFERENCE.md § Project-specific conventions.
04 同仓库更多 Skills
vue-persist
Gate Vue 3 UI on Persist hydration with useHydrated (shallowRef). Use in setup/effectScope when avoiding flash of default state on async backends.
svelte-store-persist
Gate Svelte store-based UI on Persist hydration with hydratedStore (Readable). Use for Svelte 3–4 or Svelte 5 apps that still use stores; runes UI → svelte-persist.
svelte-persist
Gate Svelte 5 runes UI on Persist hydration with hydratedRune (.current). Use for Svelte 5; for stores / Svelte 3–4 use svelte-store-persist.
solid-persist
Gate Solid UI on Persist hydration with useHydrated (Accessor). Use when avoiding flash of default state on async backends; read hydrated() in reactive scopes.
react-persist
Gate React UI on Persist hydration with useHydrated + toHydrationSignal. Use when avoiding flash of default state on async backends (IndexedDB), SSR snapshot true, or wiring HydrationSignal into React 18/19.
preact-persist
Gate Preact UI on Persist hydration with useHydrated (preact/compat useSyncExternalStore). Use when avoiding flash of default state on async backends or wiring HydrationSignal into Preact.