用途
code-self-describe 用于为代码库生成和维护自描述结构，帮助 AI 和开发者导航代码。它利用 Claude Code 的层级加载机制（搜索到文件时自动加载所在目录的 CLAUDE.md），通过三层自描述结构实现渐进式上下文理解。
主要能力
三层描述体系
| 层级 | 载体 | 内容 |
|---|---|---|
| 项目级 | 根 CLAUDE.md | 模块列表、全局约束 |
| 模块级 | 目录 CLAUDE.md | 地位、逻辑、约束、业务域清单 |
| 文件级 | 源码头部注释 | INPUT、OUTPUT、POS |
自分形架构
项目根 CLAUDE.md 提供全局视图，各模块目录下的 CLAUDE.md 提供模块视图，源文件头部注释提供文件级信息。AI 搜索到深层文件时，已自动加载前几层 CLAUDE.md，从而清晰了解整个模块。
与 keel 追溯的边界
自描述留在代码里，keel 追溯不留在代码里。判据是：代码丢了这条信息，还能不能被正确解读和维护。自描述回答“这个模块做什么、依赖谁”，对没有 keel 上下文的维护者有用；keel 追溯回答“这段代码为哪条需求写的”，对没有 keel 上下文的维护者是噪音。不得新增 @requirement / @satisfies / @verifies / @testcase 标注，存量留着不清理。
使用方式
运行模式
/code-self-describe→ 智能检测模式/code-self-describe --init→ 初始化：为项目生成完整自描述结构/code-self-describe --init src/modules/auth→ 初始化指定模块/code-self-describe --update→ 更新：根据代码变更更新描述/code-self-describe --update src/user.ts→ 更新指定文件及其所在模块/code-self-describe --audit→ 审计：检查描述新鲜度和准确性
模式对比
| 模式 | 扫描范围 | 生成 CLAUDE.md | 更新头部注释 | 用户确认 |
|---|---|---|---|---|
| init | 全项目/指定模块 | 新建 | 新增 | 逐模块 |
| update | 变更文件 (git diff) | 更新现有 | 更新变更 | 低风险自动 |
| audit | 全项目 | 仅报告 | 仅报告 | 无 |
智能检测流程
检测项目是否已有模块级 CLAUDE.md：无则自动进入 init 模式；有则检测是否有代码变更，有未同步变更建议 update 模式，无变更建议 audit 模式。
Init 模式工作流程
- 扫描项目结构：识别语言/框架、目录结构模式、业务模块边界
- 增强项目根 CLAUDE.md：已存在则追加模块描述章节，不存在则生成基础 CLAUDE.md
- 逐模块生成 CLAUDE.md：分析导入/导出关系，识别模块角色，生成描述，用户确认每个模块
- 逐文件生成头部注释：分析 import/依赖关系生成 INPUT，分析 export/公开接口生成 OUTPUT，根据目录位置和模块角色生成 POS，插入文件头部注释
- 生成描述清单报告
模块级 CLAUDE.md 模板
# <模块名>
## 地位
<在系统中的角色和位置，1-2 句话>
## 逻辑
<模块做什么，核心功能描述，3-5 句话>
## 约束
- <使用规则>
- <依赖限制>
## 业务域清单
| 文件/子模块 | 职责 |
|-------------|------|
| `xxx.ts` | <职责描述> |
源文件头部注释格式
// INPUT: UserRepository (数据访问), ValidatorService (校验)
// OUTPUT: createUser(), getUser(), updateUser() (用户 CRUD 操作)
// POS: 用户模块核心服务层，处理用户业务逻辑
注释必须放在文件最开始（在 import 语句之前），因为 AI 加载文件从头部开始。
Update 模式工作流程
- 检测变更范围：git diff --name-only 或用户指定文件/目录，识别受影响的模块
- 分析变更影响：文件级 INPUT/OUTPUT 是否变化，模块级职责是否变化，跨模块依赖是否变化
- 更新源文件头部注释：更新变更文件的 INPUT/OUTPUT/POS，保留手动添加的额外注释
- 更新模块 CLAUDE.md：更新业务域清单、逻辑描述、约束
- 向上传播更新：子模块变更更新父模块 CLAUDE.md，直到项目根 CLAUDE.md
更新传播规则：仅在公共接口变化时向上传播（内部重构不触发）；标记区分自动/手动内容（<!-- auto-generated --> 标记自动生成部分）；不修改手动编写的描述。
Audit 模式
审计内容：扫描所有 CLAUDE.md 和源文件头部注释，对比实际代码状态，生成审计报告，包括缺失描述的模块/文件、过期描述、不准确描述、描述覆盖率统计。审计模式不修改任何文件。
适用场景
- 用户需要为项目添加 AI 友好的代码描述
- 用户需要在代码变更后更新描述
- 用户需要检查描述覆盖率和准确性
- 关键词：“自描述”、“模块描述”、“生成 CLAUDE.md”、“self-describe”
限制
shell 拓扑下默认跳过
本 skill 的产物（模块级 CLAUDE.md + 源文件头注释）写在代码目录内。shell 拓扑的动机就是不让私有产物进代码仓，二者直接冲突。判据取自握手 workspace_context.capabilities.code_metadata_write_policy：explicit_opt_in → 默认跳过，仅 --force-code-docs 执行；unrestricted → 照常。不读 mode 自行分支——文件头注释写进源码文件本身，按写入策略枚举会被错误放行，故单列一项能力。默认跳过，输出 ℹ️ 说明原因，不报错。仅 --force-code-docs 显式启用。启用前 AskUserQuestion 确认「这些文件会进入 <各 code_root>，若该仓将公开请确认可接受」。代码根取自握手 workspace_context.code_roots。
生成约束
- CLAUDE.md 文件名必须使用大写（Claude Code 约定）
- 不覆盖已有的项目根 CLAUDE.md（追加或合并）
- 模块级 CLAUDE.md 必须基于实际代码分析生成
- 头部注释必须基于实际 import/export 分析
- 不为空目录或配置目录生成 CLAUDE.md
更新约束
- 只更新实际发生变化的文件
- 不修改手动编写的描述内容（通过标记区分）
- 向上传播仅在公共接口变化时触发
- 更新前必须读取现有描述
审计约束
- 审计模式不修改任何文件
- 必须生成覆盖率统计
- 必须标注过期描述的具体原因
范围约束
- 忽略隐藏目录（.git, .vscode, .idea 等）
- 忽略构建产物（dist/, build/, pycache/ 等）
- 忽略依赖目录（node_modules/, vendor/, Pods/ 等）
- 忽略测试目录的 CLAUDE.md 生成（测试文件仍生成头部注释）
Skill 协作
| 阶段 | 协作 Skill | 说明 |
|---|---|---|
| 开发完成后 | /dev-workflow | 被调用：完成检查步骤中触发 --update |
| 重构后 | /refactor | 被调用：重构完成后更新描述 |
| 项目上下文 | /onboard | 互补：CLAUDE.md 提供模块级上下文 |
| 代码追溯 | /sync | 互补：不同维度的代码标注 |
| 文件操作 | /git-safety | 配合：模块移动/重命名时同步更新 CLAUDE.md |
参考资料
- claude-md-template.md - 模块级 CLAUDE.md 模板
- header-comment-examples.md - 多语言头部注释示例
- update-rules.md - 层级更新传播规则