跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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-nextjs for a Next.js turborepo, scaffold-cli for 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.

ModeYou are here whenOutput
DesignStarting a new app, service, or surface, and the structure is not decided yetAn architecture brief
DeepenThe code works, but change is expensive: concepts scattered, seams leaking, one idea under three namesRanked opportunities, then one migrated slice
HardenThe structure is decided and keeps decaying, or agents keep doing the wrong thing in this repoWired 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.

ReferenceModeRead when
references/stack-defaults.mdDesignChoosing libraries, tooling, or deploy targets
references/api-design.mdDesign, DeepenDesigning endpoints, module contracts, request context, error shapes, or an agent-facing CLI/SDK surface
references/distributed-correctness.mdDesign, DeepenThe 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.mdDesignWriting the conventions, testing, quality-bar, or rollout and rollback sections of the brief
references/deepening-existing.mdDeepenRunning Deepen: vocabulary, opportunity patterns, output template
references/domain-language.mdDeepenWriting or fixing a glossary, resolving naming divergence, recording a decision
references/enforcement-ladder.mdHardenAdding any check to a repo that already violates it
references/guardrail-tooling.mdHardenChoosing and wiring the actual checks: dead code, duplication, cycles, module and package boundaries, file size, staleness gates
references/wayfinding.mdHardenAgents cannot find things, or keep re-deriving the same path
references/contagion-markers.mdHardenThe repo has legacy, generated, dual-path, or deliberately simplified code
[references/verification-tiers.md
阅读完整来源 ↗