Claude Code standards、commands、skills 分层与迁移清单

背景与已确认事实

这份笔记的目标不是立即改写 .claude 体系，而是先回答一个更基础的问题：哪些内容应该继续留在 standards/ 或 commands/，哪些内容才适合抽到 skills/。

已确认的事实如下：

• CLAUDE.md 负责全局总纲、默认约束和总入口；详细标准通过 standards/route.md 路由到更具体的标准文档。
• standards/workflow.md 已经明确默认工作流，并写清：任务与 skill 高度匹配时，优先用 skill，而不是手工重复流程。
• commands/commit.md 独占 /commit 的 flags、simple/full 规则、阈值、执行顺序、relevant checks 规则和提交信息生成方式。
• standards/documentation-conventions.md 已经给出 CLAUDE.md / standards / rules / commands / skills 的职责边界。
• skills/README.md 已区分 local-managed、symlink / upstream-source、mirror / upstream-copy、vendored-subrepo，说明 skills/ 不是可以统一本地重写的普通文档目录。

Note

本文只沉淀分层结论、迁移清单和实施顺序。 本轮不直接修改 .claude/standards/、.claude/commands/、.claude/skills/ 的正文。

standards / commands / skills 的职责边界

standards

standards 是默认治理层，回答的是：在没有显式命令入口时，系统默认应该怎么工作。

它适合承载：

• 默认生效的工程原则
• 默认工作流
• 质量基线与测试要求
• stack 基线
• 文档治理规则
• Git / review 的共享安全边界
• 分层导航与优先级说明

判断标准很简单：如果某条规则默认就应该生效，不应依赖 skill 是否被触发，那它就应该留在 standards。

commands

commands 是显式 slash command 入口层，回答的是：当用户执行这个命令时，具体有哪些参数、按什么顺序执行、如何做分支判断和降级。

它适合承载：

• slash command 的入口语义
• 参数定义与 argument-hint
• allowed-tools
• 执行顺序与 orchestration
• fallback、降级阈值、命令专属 heuristics
• 只在显式执行命令时才发生的流程编排

判断标准是：如果内容依赖某个 slash command 的显式入口、参数解析或执行算法，它就应该留在 commands。

skills

skills 是专项知识包和可复用子流程层，回答的是：遇到某一类任务时，有哪些可复用的方法、最佳实践、分析框架或子流程。

它适合承载：

• 特定场景下的专项最佳实践
• 可被多个任务或多个命令复用的方法论
• 审查框架、分级标准、检查思路
• planning、spec 澄清、UI review、React/Next.js 等专题知识

但 skills 有一个额外限制：先判断来源归属，再决定能不能本地维护正文。

如果某个 skill 属于 symlink / upstream-source、mirror / upstream-copy 或 vendored-subrepo，就不能把它当作普通本地文档直接搬运或重写。

三者优缺点对比

维度	standards	commands	skills
核心问题	默认应该怎么做	执行某个命令时怎么做	某类任务有哪些专项方法可复用
触发方式	默认生效	显式执行 slash command	命中场景时调用
最适合承载	原则、流程、基线、路由	参数、入口、执行算法、编排	最佳实践、评审框架、子流程、专题知识
优点	稳定、全局一致、适合做默认治理	边界清晰、可执行、便于精确约束命令行为	复用性强、适合沉淀场景知识、可被多个任务共享
缺点	如果塞入命令细节，会让默认标准膨胀	如果塞入太多通用知识，会与 standards / skills 重叠	如果承接全局治理，会造成“没触发 skill 就失效”；且受 ownership 约束
失败模式	把命令算法写成默认规则，导致边界模糊	把普适原则绑死在单一命令里，降低复用	把治理层内容误迁过去，或误改上游 / 镜像 skill
是否适合做唯一事实源	适合默认规则	适合命令契约	适合专题知识，但前提是确认可维护 ownership

迁移清单

必须留在 standards

这些内容属于默认就应生效的规则，不应依赖 skill 是否被触发：

• CLAUDE.md 的总纲、总入口和默认约束
• standards/README.md 的分层职责与优先级说明
• standards/route.md 的导航职责
• standards/workflow.md 的默认工作流、工具优先级、何时优先用 skill
• standards/principles.md / quality-and-testing.md 里的通用工程原则和质量基线
• standards/documentation-conventions.md 的文档治理规则
• standards/stack/*.md 的默认技术栈基线
• standards/git-and-review.md 的共享 Git / review 安全边界

必须留在 commands

这些内容属于显式 slash command 入口定义和执行契约：

• /commit 的 flags、simple/full 规则、阈值、执行顺序、message 生成规则
• /fix-issue、/review-pr、/merge-dependabot 这类顶层 orchestration 流程
• 任何依赖 argument-hint、allowed-tools、参数解析和入口语义的内容
• 任何“只有显式执行某个命令才发生”的流程编排

适合迁到 skills

这里的“迁”不是把整个命令或整份标准文档直接搬走，而是抽离其中可以被多个任务复用的专项知识或子流程：

• review 最佳实践、finding 分级、dismiss / fix 判断法
• commit message 选择 heuristics（但不包含 /commit flags 和执行算法）
• 通用验证 / quality pipeline 的发现流程（供多个 command 复用）
• 需求澄清、访谈式规格补全、plan 补全方法
• planning 模式、React / Next.js 最佳实践、UI 设计审查等专题知识

明确不迁

以下内容不应迁出原位，也不应在本轮改正文：

• CLAUDE.md
• standards/README.md
• standards/route.md
• standards/documentation-conventions.md
• skills/README.md 中的来源治理规则
• 所有 symlink / upstream-source、mirror / upstream-copy、vendored-subrepo 类型的 skills 正文

推荐的最小改动实施顺序

如果后续真的要开始迁移正文，建议按下面顺序推进，而不是直接大搬家：

1. 先固化边界判断标准 先用本文的三分法统一判断：默认治理留 standards，命令契约留 commands，专项可复用知识进 skills。
2. 先抽“可复用知识”，不要先动命令入口 优先从 commands/ 中抽离能复用的 review / commit heuristics / quality pipeline，而不是动 /commit、/review-pr 等命令契约本体。
3. 再抽“场景性知识”，不要动全局默认规则 从 standards/ 中只抽那些明显属于专题方法、不会影响默认治理语义的部分。
4. 每个候选 skill 先检查 ownership 只有确认是 local-managed，或者已经明确接管维护，才本地修改 skill 正文。
5. 最后再做路由和去重 当新的 skill 事实源稳定后，再回头调整路由、引用关系或文档去重，避免先删后补造成断层。

验证清单

在未来真正开始迁移正文前，至少要核对以下事项：

• 拟保留在 standards 的内容，是否仍然属于默认生效的治理规则
• 拟保留在 commands 的内容，是否确实依赖 slash 入口、参数或执行算法
• 拟迁入 skills 的内容，是否是可复用专题知识，而不是全局默认约束
• 目标 skill 的 ownership 是否允许本地维护正文
• 是否避免把同一条规则同时写进 standards、commands、skills
• 是否保留唯一事实源，而不是搬运后形成双写
• 是否仍满足“本轮只沉淀清单和笔记，不直接搬迁正文”的最小改动原则

结论

一句话总结：默认治理、优先级和基线规则留在 standards；显式 slash 入口、参数和执行算法留在 commands；专项最佳实践、可复用子流程和按场景触发的知识包适合进入 skills。

更进一步说，真正决定去向的不是“主题像不像最佳实践”，而是三件事：

1. 这条内容是不是默认就应生效
2. 它是否依赖显式 command 入口
3. 它能不能在 ownership 清晰的前提下，作为可复用知识独立存在

因此，本轮最合理的交付不是立即搬正文，而是先把边界、清单和实施顺序沉淀清楚；等后续真的要迁移时，再按 ownership 和唯一事实源原则做最小改动。