codebase-architecture
Designs module contracts, deepens existing boundaries, and installs enforceable repository guardrails. Use when asked to "design the architecture", "simplify our modules", or "harden the repo". For one feature plan use planning; for diff cleanup use tidy; for tenancy use multi-tenant-architecture.
mblode · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add mblode/agent-skills --skill codebase-architecture技能说明
name: codebase-architecture description: Designs module contracts, deepens existing boundaries, and installs enforceable repository guardrails. Use when asked to "design the architecture", "simplify our modules", or "harden the repo". For one feature plan use planning; for diff cleanup use tidy; for tenancy use multi-tenant-architecture.
Codebase Architecture
Decide a TypeScript codebase's structure, improve it where change has become expensive, and make it hold. The target is a codebase a reader can hold in their head: few surfaces, one canonical way to do each job, and behaviour where you would first look for it.
- IS: folder structures, module contracts, request context and middleware pipelines, frontend/backend boundaries; architecture briefs; domain language and decision records; domain-informed deepening; guardrail tooling, CI gates, and agent wayfinding.
- IS NOT: scaffolding a new repo (
scaffold-nextjsfor a Next.js turborepo,scaffold-clifor a TypeScript CLI), multi-tenant domain/isolation/routing (multi-tenant-architecture), the content of AGENTS.md itself (agents-md), a plan for one feature (planning), a diff-scoped cleanup pass (tidy), or structural review of a local diff (pr-reviewer).
Contents
- Modes
- References
- Design mode (new codebase)
- Deepen mode (existing codebase)
- Harden mode (make it stick)
- Validation loop
- Output template
- Excuses
- Gotchas
- Related skills
Modes
Pick by the problem, not by the artifact, and say which you picked.
| Mode | You are here when | Output |
|---|---|---|
| Design | Starting a new app, service, or surface, and the structure is not decided yet | An architecture brief |
| Deepen | The code works, but change is expensive: concepts scattered, seams leaking, one idea under three names | Ranked opportunities, then one migrated slice |
| Harden | The structure is decided and keeps decaying, or agents keep doing the wrong thing in this repo | Wired checks, markers, and recipes |
Modes compose, and running more than one is normal. Design ends in Harden, because a contract with no check is a suggestion. Deepen ends in Harden, so the new seam cannot decay back. Harden runs alone when the structure is already right and only the enforcement is missing, which is the common case in a repo that agents work in.
When two look equally right, prefer Deepen. "Agents keep using the old pattern" sounds like Harden, but if the cause is one concept living in two places, quarantine only freezes the duplicate: Deepen deletes it and Harden holds the line until that lands. Harden alone is right when the old thing genuinely has to stay.
When you cannot write to the repo (no checkout, read-only request, or a question rather than a change), each mode's output degrades to its plan: the brief, the ranked opportunities, or the named checks with their rungs. Say which checks remain unproven, since none of them are wired.
As simple as possible, no simpler. Every mode cuts: surfaces in Design, concepts in Deepen, dual paths and dormant config in Harden. The floor does not get cut: validation at trust boundaries, error handling that prevents data loss, security, accessibility, observability on anything deployed, and whatever was explicitly asked for. A simplification that reaches one of those is a bug. Where a corner is cut on purpose, mark it with its ceiling and upgrade path rather than leaving the next reader to guess whether it is finished.
Copy this to track progress, and delete the lines for modes you are not running:
Codebase architecture progress:
- [ ] Modes chosen and stated (Design / Deepen / Harden)
- [ ] Design: assumptions stated, repo shape, every contract names its check, brief written
- [ ] Deepen: git hot spots, glossary, ranked opportunities with paths, one slice migrated
- [ ] Harden: existing checks surveyed, checks picked by failure, each landed green and proven to bite
- [ ] Validation loop run for the modes used; evidence recorded, N/A items named
References
Load only when the condition applies.
| Reference | Mode | Read when |
|---|---|---|
| references/stack-defaults.md | Design | Choosing libraries, tooling, or deploy targets |
| references/api-design.md | Design, Deepen | Designing endpoints, module contracts, request context, error shapes, or an agent-facing CLI/SDK surface |
| references/distributed-correctness.md | Design, Deepen | The work provably touches an external system, webhook, retry, audit trail, or money. In Deepen you can grep for it; in Design it is a question about requirements, so confirm before loading rather than inferring it from the product's domain |
| references/brief-conventions.md | Design | Writing the conventions, testing, quality-bar, or rollout and rollback sections of the brief |
| references/deepening-existing.md | Deepen | Running Deepen: vocabulary, opportunity patterns, output template |
| references/domain-language.md | Deepen | Writing or fixing a glossary, resolving naming divergence, recording a decision |
| references/enforcement-ladder.md | Harden | Adding any check to a repo that already violates it |
| references/guardrail-tooling.md | Harden | Choosing and wiring the actual checks: dead code, duplication, cycles, module and package boundaries, file size, staleness gates |
| references/wayfinding.md | Harden | Agents cannot find things, or keep re-deriving the same path |
| references/contagion-markers.md | Harden | The repo has legacy, generated, dual-path, or deliberately simplified code |
| [references/verification-tiers.md |