init-skill 如何为 Claude Code 项目建立可进化的上下文体系

Claude Code 能直接参与项目开发，但如果只是把它当成一个“会写代码的聊天窗口”，很快就会遇到几个典型问题：

• 每次都要重新解释项目结构；
• 代码风格、命名规则、提交标准反复提醒；
• 同一个错误纠正过，下次仍然可能再犯；
• 复杂任务缺少拆解，容易一边写一边偏离目标；
• 审查、规划、实现混在一起，输出质量不稳定。

init-skill 要解决的不是“让 AI 写一段代码”，而是给 Claude Code 项目初始化一套长期可用的协作框架。它会在项目中生成 .claude/ 目录，把项目规则、专用智能体、路径级约束、工作流和学习记录组织起来，让 Claude Code 每次进入项目时都能读到稳定的上下文。

项目地址：

https://github.com/cyhzzz/init-skill

init-skill 的核心目标

init-skill 可以理解成一个 Claude Code 项目的初始化模板。它做的事情不是替代 Claude Code，而是给 Claude Code 准备一套“项目操作系统”。

这套系统主要包含四层：

整体结构可以画成这样：

flowchart TB
    A[Claude Code 启动项目] --> B[读取 CLAUDE.md]
    B --> C[理解项目目标、编码规范、完成标准]

    C --> D{任务类型判断}
    D -->|复杂设计| E[agents/architect]
    D -->|代码审查| F[agents/reviewer]
    D -->|普通实现| G[默认编码流程]

    E --> H[加载 rules/ 中的相关规则]
    F --> H
    G --> H

    H --> I[执行 skills/ 中的工作流]
    I --> J[产出代码、计划或审查结果]
    J --> K[把纠正和经验写入 memory/]

    K --> L{同类问题是否重复出现}
    L -->|是| M[晋升为 rules/ 中的长期规则]
    L -->|否| N[保留为学习记录]

关键点在最后一段：memory/ 不只是存日志，重复出现的问题会被沉淀成规则。这样项目不是一次性配置完就不变，而是会随着使用过程逐渐变得更贴合项目习惯。

第一层：CLAUDE.md 是项目的认知核心

在 Claude Code 项目里，CLAUDE.md 通常是最重要的上下文文件。它相当于给 AI 的项目说明书，但它不应该只写“这是一个什么项目”，还要写清楚 AI 在这个项目里应该如何判断、如何完成任务。

一个有效的 CLAUDE.md 通常包含几类信息：

# Project Guide

## 项目目标
描述项目解决的问题、主要用户、核心业务边界。

## 技术栈
- Runtime:
- Framework:
- Database:
- Test:
- Build:

## 开发原则
- 优先保持现有架构一致，不随意引入新依赖。
- 修改公共接口时必须同步更新调用方和测试。
- 复杂逻辑需要拆成可测试的小函数。

## 完成标准
- 代码能通过类型检查。
- 相关测试必须补齐或更新。
- 修改行为需要同步更新文档或注释。
- 不允许留下临时调试代码。

## 编码规范
- 命名方式：
- 错误处理：
- 日志规范：
- API 返回结构：

CLAUDE.md 的价值在于把“每次都要说一遍”的隐性要求变成显式规则。比如项目约定所有 API 错误都要返回统一结构，如果只在对话里临时提醒，Claude Code 很容易在另一个任务里忘掉；写进 CLAUDE.md 后，它会成为每次工作的基础上下文。

适合写进 CLAUDE.md 的内容，一般有三个判断标准：

CLAUDE.md 不宜写成一个无限膨胀的大杂烩。全局稳定的信息放在这里，局部规则、可复用流程和历史经验交给后面的目录承载。

第二层：agents 让不同任务交给不同角色

复杂项目里，规划、实现、审查不是同一类工作。如果所有事情都让 Claude Code 以同一种模式处理，容易出现两个问题：

1. 做复杂需求时直接开始写代码，缺少架构拆解；
2. 写完代码后没有独立审查视角，容易遗漏边界条件。

init-skill 引入 agents/ 的意义，就是把不同类型的任务拆给专用子智能体。常见角色包括：

可以把它理解成一个小型开发流程：

sequenceDiagram
    participant User as 开发者
    participant Claude as Claude Code
    participant Architect as architect
    participant Reviewer as reviewer
    participant Codebase as 项目代码

    User->>Claude: 提出复杂开发任务
    Claude->>Architect: 请求拆解方案
    Architect-->>Claude: 返回实现计划、影响范围、风险点
    Claude->>Codebase: 按计划修改代码
    Claude->>Reviewer: 请求提交前审查
    Reviewer-->>Claude: 返回问题清单和修改建议
    Claude->>Codebase: 根据审查结果修正
    Claude-->>User: 返回最终结果和变更说明

这种分工能减少“边想边写”的混乱。architect 更关注任务是否拆得合理，reviewer 更关注结果是否符合规范。即使最终仍然由 Claude Code 完成代码修改，前后两个角色也能提供额外约束。

一个 architect 的角色说明可以这样写：

# architect

你负责复杂任务的技术方案设计，不直接修改代码。

输出必须包含：
- 目标拆解
- 涉及文件或模块
- 数据流或调用链变化
- 兼容性影响
- 测试策略
- 潜在风险

遇到需求不明确时，先列出假设，不要直接实现。

一个 reviewer 的角色说明可以这样写：

# reviewer

你负责提交前代码审查。

重点检查：
- 是否符合 CLAUDE.md 中的完成标准
- 是否违反 rules/ 中的路径规则
- 是否引入安全风险
- 是否缺少测试
- 是否改变已有行为但没有说明
- 是否存在重复逻辑或过度设计

输出格式：
- 必须修改
- 建议修改
- 可以接受

角色文件的核心不是“写得像人设”，而是明确输入、职责边界和输出格式。越具体，Claude Code 越容易稳定执行。

第三层：rules 按路径和场景加载约束

很多项目规则不是全局生效的。比如：

• api/ 目录关注接口设计、鉴权、错误码；
• db/ 目录关注迁移脚本、事务、索引；
• frontend/ 目录关注组件结构、状态管理、可访问性；
• security/ 规则只在涉及认证、权限、加密时重点使用；
• performance/ 规则只在热点路径、批量任务、查询优化时重点使用。

如果把所有规则都塞进 CLAUDE.md，上下文会越来越长，而且 Claude Code 每次都要处理大量无关信息。rules/ 的作用是把规则按作用域拆开，需要时再加载。

一种可读性较好的目录结构如下：

.claude/
  CLAUDE.md
  agents/
    architect.md
    reviewer.md
  rules/
    api.md
    security.md
    performance.md
    database.md
    frontend.md
  skills/
    implement-feature.md
    review-before-submit.md
    fix-bug.md
  memory/
    corrections.md
    decisions.md

规则文件可以按主题组织。例如 API 规则：

# API Rules

适用范围：
- `src/api/**`
- `src/routes/**`
- `controllers/**`

规则：
- 所有接口必须进行参数校验。
- 错误响应使用统一结构：`code`、`message`、`details`。
- 不在 controller 中写复杂业务逻辑，业务逻辑下沉到 service。
- 新增公开接口必须补充测试。
- 涉及权限的数据读取必须显式检查当前用户身份。

安全规则可以更关注不可违反的边界：

# Security Rules

必须遵守：
- 不把 token、密钥、密码写入代码或日志。
- 不信任客户端传入的用户身份、角色、价格、权限字段。
- SQL 查询必须使用参数化语句或 ORM 安全接口。
- 文件上传必须检查类型、大小和存储路径。
- 涉及权限变更时，必须说明调用方身份和授权来源。

rules/ 的设计重点是“按需约束”。它让 Claude Code 在处理具体文件时，更容易拿到与当前任务相关的规则，而不是被一整份超长项目说明淹没。

第四层：skills 和 memory 构成进化机制

前三层解决的是“启动时知道什么”，第四层解决的是“使用后学到什么”。

skills/ 适合放固定工作流。比如实现新功能时，不希望 Claude Code 直接改代码，而是按一个流程走：

# implement-feature

流程：
1. 阅读相关代码和 CLAUDE.md。
2. 如果任务影响多个模块，先调用 architect 产出方案。
3. 列出将要修改的文件。
4. 小步修改，每一步保持可解释。
5. 补充或更新测试。
6. 调用 reviewer 做提交前审查。
7. 修复审查中标记为“必须修改”的问题。
8. 输出变更摘要、测试结果和剩余风险。

memory/ 适合放项目使用过程中的经验。比如开发者纠正过一次：

# corrections

## 2026-06-07
问题：生成 API 时把业务错误直接返回了 HTTP 500。
纠正：业务可预期错误应该返回 4xx，并使用统一错误结构。
适用范围：API controller 和 service。

如果同类问题出现多次，就不应该继续停留在 memory/。它应该被提升成 rules/api.md 中的长期规则：

# API Rules

- 业务可预期错误不能返回 HTTP 500。
- 参数错误返回 400。
- 未认证返回 401。
- 无权限返回 403。
- 资源不存在返回 404。
- 错误响应必须使用统一结构。

这种机制就是“项目自进化”的关键：一次纠正先记录，重复出现就固化。AI 不只是完成当前任务，还会把项目偏好沉淀下来。

流程可以这样理解：

flowchart LR
    A[开发者纠正 Claude Code] --> B[写入 memory/corrections.md]
    B --> C{是否重复出现}
    C -->|一次性问题| D[保留为经验记录]
    C -->|多次出现| E[整理成稳定规则]
    E --> F[写入 rules/ 对应文件]
    F --> G[后续任务自动受规则约束]

这套机制的价值不在于“记录很多东西”，而在于区分临时经验和长期规则。所有纠正都永久变成规则，会让规则库变得臃肿；只有重复出现、影响范围明确的问题，才值得晋升。

适合使用 init-skill 的项目

init-skill 更适合上下文复杂、协作规则明确、需要长期维护的项目。小脚本或一次性实验项目也能用，但收益没那么明显。

判断是否需要这套结构，可以看三个问题：

• 是否经常需要反复提醒 Claude Code 同一条规则？
• 是否存在多个目录、多个模块，各自有不同开发约束？
• 是否希望 AI 在项目中保留纠错记录，并把重复问题变成长期规则？

如果答案大多是肯定的，.claude/ 目录就不只是配置文件，而是项目工程规范的一部分。

上手方式

使用 init-skill 的入口是 GitHub 仓库：

https://github.com/cyhzzz/init-skill

实际使用时，可以按仓库说明把 skill 加入 Claude Code 环境，然后在目标项目中执行初始化。初始化完成后，项目里会出现类似结构：

your-project/
  .claude/
    CLAUDE.md
    agents/
    rules/
    skills/
    memory/
  src/
  tests/
  package.json

如果暂时不想直接运行工具，也可以按同样思路手动搭一版最小结构：

mkdir -p .claude/agents .claude/rules .claude/skills .claude/memory

touch .claude/CLAUDE.md
touch .claude/agents/architect.md
touch .claude/agents/reviewer.md
touch .claude/rules/api.md
touch .claude/rules/security.md
touch .claude/skills/implement-feature.md
touch .claude/memory/corrections.md

最小可用版本不需要一次写得很完整，只要先覆盖最容易影响产出质量的内容：

初始化以后，和 Claude Code 协作时可以明确要求它遵守这套结构：

请先阅读 .claude/CLAUDE.md。
如果任务涉及接口或权限，请加载 .claude/rules/api.md 和 .claude/rules/security.md。
如果改动超过 3 个文件，请先使用 architect 方式给出方案。
实现完成后，请按 reviewer 的检查清单做一次提交前审查。
如果我纠正了你的实现，请把纠正记录到 .claude/memory/corrections.md。

使用时要注意的几个坑

1. CLAUDE.md 不要写成超长说明书

CLAUDE.md 应该放全局、稳定、高频的信息。目录级规则、专项安全要求、固定流程都拆出去，否则主上下文会越来越重，真正重要的约束反而不突出。

2. rules 要能执行，不要写口号

规则应该具体到 Claude Code 能判断是否违反。

不够好的写法：

- 注意代码质量。
- 保证接口安全。
- 提升性能。

更好的写法：

- controller 中不写超过 30 行的业务逻辑，复杂逻辑放到 service。
- 涉及用户数据读取时，必须检查当前用户是否有访问权限。
- 列表接口必须考虑分页，不能默认返回全量数据。

3. memory 需要定期整理

memory/ 如果只追加不整理，会变成杂乱日志。比较好的做法是：

• 偶发问题保留在 memory/；
• 重复问题提炼到 rules/；
• 过期决策标记废弃；
• 与当前项目无关的记录删除。

4. agent 职责不要重叠

architect 负责方案，reviewer 负责审查，实现工作交给主流程。如果每个 agent 都既规划又实现又审查，角色拆分就失去了意义。

5. 规则晋升要谨慎

不是每次纠正都要变成规则。适合晋升的纠正通常满足几个条件：

• 同类问题出现不止一次；
• 对代码质量或安全有明确影响；
• 能写成可执行、可检查的规则；
• 适用范围清楚，不会误伤其他场景。

init-skill 的价值

init-skill 把 Claude Code 项目从“临时对话驱动”推进到“规则和记忆驱动”。它不是单纯增加几个配置文件，而是把 AI 协作拆成四个层次：

CLAUDE.md 负责全局认知
agents/   负责专业分工
rules/    负责局部约束
skills/   负责固定流程
memory/   负责经验沉淀

当项目变复杂后，真正影响 AI 编程质量的往往不是某一次提示词写得多漂亮，而是项目能不能持续提供清晰、稳定、可演进的上下文。init-skill 提供的正是这套骨架：让 Claude Code 知道项目规则，按合适流程工作，并把反复纠正的问题沉淀成长期约束。