improve-codebase-architecture
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
- License 许可
- GPL-3.0
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- improve-codebase-architecture
- description
- Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
- disable-model-invocation
- true
02 资源文件 1
- 参考文档HTML-REPORT.md4.3 KB
03 SKILL.md 正文
Improve Codebase Architecture
Surface architectural friction and propose deepening opportunities that improve testability and AI-navigability by turning shallow modules into deep ones.
Load /codebase-design for the architecture vocabulary, principles, dependency
categories, and repository-authority rules. Use the relevant domain glossary's
terms for the code under review, and do not re-litigate governing principles or
ADRs without concrete friction that warrants reopening them.
1. Explore and verify
Follow the repository entrypoint and the domain and architecture authorities
identified by /codebase-design. Missing optional domain or ADR files are not a
blocker.
Use authorized Explore agents for breadth when the codebase warrants fan-out. When delegation is unavailable or policy-disallowed, scan locally and state that reason. In either case, do the depth and evidence work directly: read the relevant files and call sites yourself, and support promoted candidates with compact counts, deletion-test results, and exact line references.
Explore organically:
- Where does one concept require bouncing among many small modules?
- Which modules are shallow?
- Where were pure helpers extracted for tests while call-site bugs stayed hidden?
- Where does coupled behavior leak across seams?
- What is difficult to test through its current interface?
Apply /codebase-design's deletion test. Promote only friction that survives
call-site and authority verification; if a type, caller, test, principle, or ADR
already neutralizes the claim, drop or downgrade it.
2. Present the HTML report
Write a fresh self-contained report outside the repository at
$TMPDIR/architecture-review-<timestamp>.html, falling back to /tmp (or
%TEMP% on Windows). Follow HTML-REPORT.md for the visual,
evidence, vocabulary, and card contract.
Open the report when the environment allows, using the OS-appropriate command;
on WSL prefer wslview or Windows Explorer. Dispatch terminal openers detached
so they cannot hold the run open. When command execution is sandboxed, obtain
the environment's normal GUI or host-execution authorization before dispatching
the opener. Capture its immediate stderr and exit status; treat explicit
launcher refusal output, including snap-confine refusing to continue, as a
failed open even when xdg-open or gio returns zero. Apply the same GUI or
host authorization to any named-browser fallback instead of retrying it inside
the restricted sandbox. Always print both the exact opener command and the
absolute report path, because dispatch success does not prove a visible GUI.
Failure to open a GUI does not invalidate a report that exists at the printed
path.
Use relevant principle or ADR callouts only when an authority conflicts with or endorses a verified candidate. End with one Top recommendation.
Do not propose interfaces in the report. After writing it, ask exactly: "Which of these would you like to explore?"
3. Grill the selected candidate
Once the user picks a candidate, run /grilling to resolve constraints,
dependencies, module shape, seam placement, hidden implementation, and surviving
tests. Respect every explicit mutation limit from the user.
Use /domain-modeling when resolved terms or durable decisions require domain
artifacts, and let that skill own glossary/ADR routing and closeout. For
alternative interface designs, use /codebase-design's design-it-twice flow.
4. Hand off authorized implementation
If the user asks to implement after grilling, first recap the selected modules, domain and architectural authorities, accepted constraints, domain-model changes, behavior posture, and expected tests/docs. Default to behavior-preserving work unless the user explicitly approved a behavior change.
Then use the repository's implementation workflow (/implement for published
issue or PRD work; otherwise the local coding guidelines). Keep edits scoped to
the agreed candidate and verify focused tests plus relevant full gates, including
doc, ADR, or principle checks when those authorities changed or justified the
design.
04 同仓库更多 Skills
triage
Move issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.
triage
Move issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.
triage
Move issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.
to-prd
Turn the current conversation into a PRD and publish it to the project issue tracker — no requirements interview, just synthesis of what you've already discussed; the seam confirmation is the sole checkpoint.
to-prd
Turn the current conversation into a PRD and publish it to the project issue tracker — no requirements interview, just synthesis of what you've already discussed; the seam confirmation is the sole checkpoint.
to-prd
Turn the current conversation into a PRD and publish it to the project issue tracker — no requirements interview, just synthesis of what you've already discussed; the seam confirmation is the sole checkpoint.