Finishing a Development Branch
obra/superpowers
Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.
用于设计深模块的共享词汇。适用于用户想设计或改进模块接口、寻找深化机会、决定 seam 放在哪里、让代码更容易测试或更适合 AI 导航，或其他技能需要深模块词汇时。
Install Codebase Design
$ npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install vinvcn/mattpocock-skills-zh-CN codebase-design --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/vinvcn/mattpocock-skills-zh-CN.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/engineering/codebase-design .claude/skills/codebase-design && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "codebase-design" agent skill from https://github.com/vinvcn/mattpocock-skills-zh-CN/tree/main/skills/engineering/codebase-design into .claude/skills/codebase-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codebase-design", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/vinvcn/mattpocock-skills-zh-CN/tree/main/skills/engineering/codebase-designType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install vinvcn/mattpocock-skills-zh-CN codebase-design --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/vinvcn/mattpocock-skills-zh-CN.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/engineering/codebase-design .agents/skills/codebase-design && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "codebase-design" agent skill from https://github.com/vinvcn/mattpocock-skills-zh-CN/tree/main/skills/engineering/codebase-design into .agents/skills/codebase-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codebase-design", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install vinvcn/mattpocock-skills-zh-CN codebase-design --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/vinvcn/mattpocock-skills-zh-CN.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/engineering/codebase-design .cursor/skills/codebase-design && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "codebase-design" agent skill from https://github.com/vinvcn/mattpocock-skills-zh-CN/tree/main/skills/engineering/codebase-design into .cursor/skills/codebase-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codebase-design", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/vinvcn/mattpocock-skills-zh-CN.git --path skills/engineering/codebase-design--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install vinvcn/mattpocock-skills-zh-CN codebase-design --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/vinvcn/mattpocock-skills-zh-CN.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/engineering/codebase-design .gemini/skills/codebase-design && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "codebase-design" agent skill from https://github.com/vinvcn/mattpocock-skills-zh-CN/tree/main/skills/engineering/codebase-design into .gemini/skills/codebase-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codebase-design", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install vinvcn/mattpocock-skills-zh-CN codebase-designInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/vinvcn/mattpocock-skills-zh-CN.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/engineering/codebase-design .github/skills/codebase-design && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "codebase-design" agent skill from https://github.com/vinvcn/mattpocock-skills-zh-CN/tree/main/skills/engineering/codebase-design into .github/skills/codebase-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codebase-design", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install vinvcn/mattpocock-skills-zh-CN codebase-design --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/vinvcn/mattpocock-skills-zh-CN.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/engineering/codebase-design .opencode/skills/codebase-design && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "codebase-design" agent skill from https://github.com/vinvcn/mattpocock-skills-zh-CN/tree/main/skills/engineering/codebase-design into .opencode/skills/codebase-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "codebase-design", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
codebase-design- GitHub stars
- 4.6k
- Token cost
- ~1.1k tokens
- SKILL.md length
- 351 words
- Files
- 4
- Skills in repo
- 33
- Repo updated
- First seen
- Licence
- MIT
At a glance
用于设计深模块的共享词汇。适用于用户想设计或改进模块接口、寻找深化机会、决定 seam 放在哪里、让代码更容易测试或更适合 AI 导航，或其他技能需要深模块词汇时。
- Works in 3 steps: Accept dependencies, don't create them. → Return results, don't produce side… → Small surface area. 更少 methods = 需要更少…
- Development work in your project
- SKILL.md covers Glossary, Deep vs shallow, Principles and Designing for testability, plus 3 more sections
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
Codebase Design is an agent skill from vinvcn/mattpocock-skills-zh-CN. 用于设计深模块的共享词汇。适用于用户想设计或改进模块接口、寻找深化机会、决定 seam 放在哪里、让代码更容易测试或更适合 AI 导航，或其他技能需要深模块词汇时。
Its SKILL.md is about 1.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 4 other files (for example `DEEPENING.md`, `DESIGN-IT-TWICE.md` and `agents/openai.yaml`).
It sits in Development. The repository describes itself as: 这是 mattpocock/skills 的简体中文本地化版本。 The licence is MIT.
When your agent uses it
- Development work in your project
Example prompts
- “/codebase-design”
Workflow steps
3 steps, taken from the first numbered list in SKILL.md.
- Accept dependencies, don't create them.
- Return results, don't produce side effects.
- Small surface area. 更少 methods = 需要更少 tests。更少 params = 更简单的 test setup。
What it can do on your machine
Read from SKILL.md and the folder at commit 3f92a83. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are typescript).
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Codebase Design loads about 1.1k tokens when it runs. Until then it costs about 25 tokens; SKILL.md has 351 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from vinvcn/mattpocock-skills-zh-CN at commit 3f92a83, republished under its MIT licence (© vinvcn). 351 words, ~1,102 tokens.
Download SKILL.mdSave it as
.claude/skills/codebase-design/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.- name
- codebase-design
- description
- 用于设计深模块的共享词汇。适用于用户想设计或改进模块接口、寻找深化机会、决定 seam 放在哪里、让代码更容易测试或更适合 AI 导航，或其他技能需要深模块词汇时。
Codebase Design
设计 deep modules：把大量行为放在小 interface 之后，把 interface 放在清晰 seam 上，并通过该 interface 测试。凡是在设计或重构代码时，都使用这套语言和原则。目标是给 callers 带来 leverage，给 maintainers 带来 locality，并让每个人都更容易测试。
Glossary
准确使用这些术语，不要替换成 "component"、"service"、"API" 或 "boundary"。一致语言就是重点。
Module - 任何拥有 interface 和 implementation 的东西。它故意不限定尺度：function、class、package，或跨层 slice 都可以。Avoid: unit, component, service.
Interface - caller 为了正确使用 module 必须知道的一切：type signature，以及 invariants、ordering constraints、error modes、required configuration 和 performance characteristics。Avoid: API, signature（太窄，只指 type-level surface）。
Implementation - module 内部的代码体。它不同于 Adapter：一个东西可以是小 adapter 但有大 implementation（Postgres repo），也可以是大 adapter 但 implementation 很小（in-memory fake）。讨论 seam 时说 adapter；其他时候说 implementation。
Depth - interface 上的 leverage：caller（或 test）每学习一单位 interface，就能触达多少行为。大量行为藏在小 interface 后面时，module 是 deep；interface 几乎和 implementation 一样复杂时，module 是 shallow。
Seam（Michael Feathers）- 你可以在不编辑当前位置的情况下改变行为的地方；也就是 module 的 interface 所在的 location。seam 放在哪里是独立设计决策，不同于 seam 后面放什么。Avoid: boundary（它和 DDD bounded context 过载）。
Adapter - 在 seam 上满足某个 interface 的具体东西。描述的是 role（填哪个槽位），不是 substance（内部是什么）。
Leverage - callers 从 depth 获得的收益：每学习一单位 interface，就得到更多能力。一个 implementation 会在 N 个 call sites 和 M 个 tests 中回本。
Locality - maintainers 从 depth 获得的收益：change、bugs、knowledge 和 verification 集中在一个地方，而不是散到 callers 里。修一次，到处都修好。
Deep vs shallow
Deep module = small interface + lots of implementation:
+------------------+
| Small Interface | -> few methods, simple params
+------------------+
| |
| Deep | -> complex logic hidden
| Implementation |
| |
+------------------+Shallow module = large interface + little implementation（避免）：
+-------------------------------+
| Large Interface | -> many methods, complex params
+-------------------------------+
| Thin Implementation | -> mostly pass-through
+-------------------------------+设计 interface 时问：
- 我能减少 methods 数量吗？
- 我能简化 parameters 吗？
- 我能把更多复杂度藏到内部吗？
Principles
- Depth 是 interface 的属性，不是 implementation 的属性。 Deep module 内部可以由小的、mockable、swappable parts 组成，只是它们不属于 interface。一个 module 可以同时拥有 internal seams（implementation 私有，供自身 tests 使用）和位于 interface 的 external seam。
- Deletion test。 想象删除这个 module。如果复杂度消失了，它只是 pass-through。如果复杂度重新散落到 N 个 callers 里，它就在发挥价值。
- Interface is the test surface。 Callers 和 tests 穿过同一个 seam。若你想测试 interface 之后的内部细节，这个 module 形状可能不对。
- One adapter means a hypothetical seam. Two adapters means a real one. 除非确实有东西会跨 seam 变化，否则不要引入 seam。
Show full SKILL.md (154 more words)Show less
Designing for testability
好的 interfaces 让测试自然发生：
Accept dependencies, don't create them.
typescript // Testable function processOrder(order, paymentGateway) {} // Hard to test function processOrder(order) { const gateway = new StripeGateway(); }Return results, don't produce side effects.
typescript // Testable function calculateDiscount(cart): Discount {} // Hard to test function applyDiscount(cart): void { cart.total -= discount; }Small surface area. 更少 methods = 需要更少 tests。更少 params = 更简单的 test setup。
Relationships
- 一个 Module 恰好有一个 Interface（它呈现给 callers 和 tests 的 surface）。
- Depth 是 Module 的属性，并以其 Interface 衡量。
- Seam 是 Module 的 Interface 所在的位置。
- Adapter 位于 Seam 上，并满足 Interface。
- Depth 为 callers 产生 Leverage，为 maintainers 产生 Locality。
Rejected framings
- 把 depth 当作 implementation-lines 与 interface-lines 的比例（Ousterhout）：这会奖励 padding implementation。这里使用 depth-as-leverage。
- 把 "Interface" 理解为 TypeScript
interfacekeyword 或 class public methods：太窄；这里的 interface 包括 caller 必须知道的所有事实。 - "Boundary"：与 DDD bounded context 过载。说 seam 或 interface。
Going deeper
- Deepening a cluster given its dependencies - 见 DEEPENING.md：dependency categories、seam discipline 和 replace-don't-layer testing。
- Exploring alternative interfaces - 见 DESIGN-IT-TWICE.md：启动并行 sub-agents，用几种截然不同的方式设计 interface，再按 depth、locality 和 seam placement 比较。
© vinvcn, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 3 other files in skills/engineering/codebase-design of vinvcn/mattpocock-skills-zh-CN.
- SKILL.md
- DEEPENING.md
- DESIGN-IT-TWICE.md
- agents/openai.yaml
Open the folder on GitHubat commit 3f92a83
Compare with similar skills
Codebase Design next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Codebase Design this skillvinvcn/mattpocock-skills-zh-CN | 4.6k | — | ~1.1k | Automated safety check: Pass | MIT | |
| Finishing a Development Branchobra/superpowers | 296k | 5 repos | ~1.9k | Automated safety check: Pass | MIT | |
| Typescript Advanced Typesrolling-scopes/rsschool-app | 10k | 24 repos | ~4.2k | Automated safety check: Pass | MPL-2.0 | |
| PR Babysitteropeninterpreter/openinterpreter | 69k | 3 repos | ~4.2k | Automated safety check: Pass | Apache-2.0 | |
| Code Review ChecklistshareAI-lab/learn-claude-code | 78k | 5 repos | ~1.1k | Automated safety check: Pass | MIT | |
| Greplooponyx-dot-app/onyx | 32k | 4 repos | ~3.3k | Automated safety check: Pass | MIT |
Similar skills
Typescript Advanced Types
rolling-scopes/rsschool-app
Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications.
PR Babysitter
openinterpreter/openinterpreter
Watches an open GitHub pull request until it merges, handling review comments, diagnosing CI failures and retrying flaky checks along the way.
Code Review Checklist
shareAI-lab/learn-claude-code
Reviews code against a five-part checklist covering security, correctness, performance, maintainability and testing, and reports findings in a fixed format.
Greploop
onyx-dot-app/onyx
Iteratively improves a PR (GitHub), MR (GitLab), or shelved changelist (Perforce) until Greptile gives it a 5/5 confidence score with zero unresolved comments.
Guidelines
akash-network/node
Behavioral guidelines to reduce common LLM coding mistakes. An agent skill from akash-network/node.
More from vinvcn/mattpocock-skills-zh-CN
All 33 skills in this repoGit Guardrails Claude Code
vinvcn/mattpocock-skills-zh-CN
设置 Claude Code hooks，在危险 git commands（push、reset --hard、clean、branch -D 等）执行前阻止它们。适用于用户想防止破坏性 git 操作、添加 git safety hooks，或在 Claude Code 中阻止 git push/reset 时。
Diagnosing Bugs
vinvcn/mattpocock-skills-zh-CN
面向棘手缺陷和性能回退的诊断循环。适用于用户说 “diagnose” / “debug this”，或报告某些东西 broken、throwing、failing、slow 时。
Domain Modeling
vinvcn/mattpocock-skills-zh-CN
构建并打磨项目的领域模型。适用于讨论 codebase 术语、编写或编辑 CONTEXT.md，或记录或编辑 ADR. An agent skill from vinvcn/mattpocock-skills-zh-CN.
Migrate To Shoehorn
vinvcn/mattpocock-skills-zh-CN
将测试文件从 as 类型断言迁移到 @total-typescript/shoehorn。适用于用户提到 shoehorn、想替换测试中的 as，或需要局部测试数据时。
PR
vinvcn/mattpocock-skills-zh-CN
用于撰写 PR 正文。适用于用户要求起草、改写或改进 PR 正文，或希望 PR 更便于审阅时. An agent skill from vinvcn/mattpocock-skills-zh-CN.
Scaffold Exercises
vinvcn/mattpocock-skills-zh-CN
创建包含章节、题目、答案和讲解的练习目录结构，并确保通过 linting。适用于用户想 scaffold exercises、创建 exercise stubs，或设置新的课程章节时。
Related
Categories
Questions about Codebase Design
What does Codebase Design do?
用于设计深模块的共享词汇。适用于用户想设计或改进模块接口、寻找深化机会、决定 seam 放在哪里、让代码更容易测试或更适合 AI 导航，或其他技能需要深模块词汇时。. Codebase Design is an agent skill from vinvcn/mattpocock-skills-zh-CN.
When should I use Codebase Design?
Codebase Design fits situations like: development work in your project.
How do I install Codebase Design in Claude Code?
Run `npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -a claude-code`. Or copy the skill folder (skills/engineering/codebase-design in vinvcn/mattpocock-skills-zh-CN) into .claude/skills/codebase-design in your project. Claude Code loads it when a task matches its description.
How do I install Codebase Design in Codex?
Run `npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -a codex`. Or copy the skill folder (skills/engineering/codebase-design in vinvcn/mattpocock-skills-zh-CN) into .agents/skills/codebase-design in your project. Codex loads it when a task matches its description.
Can I use Codebase Design in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add vinvcn/mattpocock-skills-zh-CN --skill codebase-design -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/codebase-design, .gemini/skills/codebase-design, .github/skills/codebase-design and .opencode/skills/codebase-design in your project.
What does Codebase Design need to run?
SKILL.md names no scripts, command-line tools or credentials: Codebase Design is instructions for the agent only.
Does Codebase Design access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Codebase Design safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Codebase Design use?
Codebase Design is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Codebase Design use?
About 1.1k tokens (SKILL.md is roughly 4.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Codebase Design?
Skills that share tags, products or a category with Codebase Design: Finishing a Development Branch (obra/superpowers, 296k stars), Typescript Advanced Types (rolling-scopes/rsschool-app, 10k stars), PR Babysitter (openinterpreter/openinterpreter, 69k stars) and Code Review Checklist (shareAI-lab/learn-claude-code, 78k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Codebase Design?
vinvcn (a GitHub user) maintains it in vinvcn/mattpocock-skills-zh-CN, which has 4,635 GitHub stars. The repository holds 33 skills in this directory. The repository was last updated on September 28, 2026.
Source: vinvcn/mattpocock-skills-zh-CN on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.