代码自描述

为代码库生成和维护自描述结构，利用 Claude Code 的层级加载机制实现渐进式上下文理解。

语言规则

支持中英文提问
统一中文回复
CLAUDE.md 文件内容使用中文
源文件头部注释使用中文

触发条件

用户需要为项目添加 AI 友好的代码描述
用户需要在代码变更后更新描述
用户需要检查描述覆盖率和准确性
关键词："自描述"、"模块描述"、"生成 CLAUDE.md"、"self-describe"

核心概念

自分形架构

利用 Claude Code 的分级加载机制（搜索到文件时自动加载所在目录的 CLAUDE.md），通过三层自描述结构提升 AI 的代码理解：

项目根 CLAUDE.md ← 全局视图
    │
    ├── src/modules/auth/CLAUDE.md ← 模块视图
    │   ├── auth.service.ts  ← 文件头部 INPUT/OUTPUT/POS
    │   ├── auth.guard.ts
    │   └── auth.controller.ts
    │
    └── src/modules/user/CLAUDE.md ← 模块视图
        ├── user.service.ts
        └── user.repository.ts

AI 搜索到第五层文件时，已自动加载前四层 CLAUDE.md，对整个模块的了解无比清晰。

三层描述体系

层级	载体	内容
项目级	根 CLAUDE.md	模块列表、全局约束
模块级	目录 CLAUDE.md	地位、逻辑、约束、业务域清单
文件级	源码头部注释	INPUT、OUTPUT、POS

与代码追溯标注的关系

自描述和 DevDocs 追溯标注服务于不同维度，两者共存互补：

维度	自描述 (INPUT/OUTPUT/POS)	追溯标注 (@requirement/@satisfies)
目的	帮助 AI 理解模块结构和依赖	追踪需求实现状态
粒度	文件级	方法/函数级
维度	架构理解（模块做什么）	需求追溯（为什么做）
更新时机	代码结构变更时	需求实现/变更时
位置	文件最开始	具体的类/函数/方法上方

运行模式

/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 模式

工作流程

1. 扫描项目结构
   ├── 识别语言/框架（package.json, go.mod, Cargo.toml 等）
   ├── 识别目录结构模式（src/, lib/, modules/ 等）
   └── 识别业务模块边界
           │
           ▼
2. 增强项目根 CLAUDE.md
   ├── 已存在：追加模块描述章节（不覆盖现有内容）
   └── 不存在：生成基础 CLAUDE.md
           │
           ▼
3. 逐模块生成 CLAUDE.md
   ├── 分析模块内文件的导入/导出关系
   ├── 识别模块角色（服务层、数据层、接口层等）
   ├── 生成 CLAUDE.md（地位/逻辑/约束/业务域清单）
   └── 用户确认每个模块的描述
           │
           ▼
4. 逐文件生成头部注释
   ├── 分析 import/依赖关系 → INPUT
   ├── 分析 export/公开接口 → OUTPUT
   ├── 根据目录位置和模块角色 → POS
   └── 插入文件头部注释
           │
           ▼
5. 生成描述清单报告

模块级 CLAUDE.md 模板

详细模板和示例见 templates/claude-md-template.md

# <模块名>

## 地位
<在系统中的角色和位置，1-2 句话>

## 逻辑
<模块做什么，核心功能描述，3-5 句话>

## 约束
- <使用规则>
- <依赖限制>

## 业务域清单
| 文件/子模块 | 职责 |
|-------------|------|
| `xxx.ts` | <职责描述> |

源文件头部注释格式

多语言示例见 templates/header-comment-examples.md

// INPUT: UserRepository (数据访问), ValidatorService (校验)
// OUTPUT: createUser(), getUser(), updateUser() (用户 CRUD 操作)
// POS: 用户模块核心服务层，处理用户业务逻辑

注释必须放在文件最开始（在 import 语句之前），因为 AI 加载文件从头部开始。

Update 模式

工作流程

1. 检测变更范围
   ├── git diff --name-only（对比上次提交）
   ├── 或用户指定文件/目录
   └── 识别受影响的模块
           │
           ▼
2. 分析变更影响
   ├── 文件级：INPUT/OUTPUT 是否变化
   ├── 模块级：模块职责是否变化
   └── 跨模块：模块间依赖是否变化
           │
           ▼
3. 更新源文件头部注释
   ├── 更新变更文件的 INPUT/OUTPUT/POS
   └── 保留手动添加的额外注释
           │
           ▼
4. 更新模块 CLAUDE.md
   ├── 更新业务域清单（新增/删除文件）
   ├── 更新逻辑描述（如模块职责变化）
   └── 更新约束（如新增依赖规则）
           │
           ▼
5. 向上传播更新
   ├── 子模块变更 → 更新父模块 CLAUDE.md
   └── 直到项目根 CLAUDE.md 为止

更新传播规则

详细规则见 templates/update-rules.md

仅在公共接口变化时向上传播（内部重构不触发）
标记区分自动/手动内容（ 标记自动生成部分）
不修改手动编写的描述

Audit 模式

审计内容

1. 扫描所有 CLAUDE.md 和源文件头部注释
2. 对比实际代码状态
3. 生成审计报告：
   ├── 缺失描述的模块/文件
   ├── 过期描述（代码已变更但描述未更新）
   ├── 不准确描述（INPUT/OUTPUT 与实际不符）
   └── 描述覆盖率统计

审计报告格式（终端输出）

📊 代码自描述审计报告

覆盖率:
  模块级 CLAUDE.md: 8/12 (67%)
  文件头部注释:     45/62 (73%)

⚠️  缺失描述:
  - src/modules/payment/CLAUDE.md (缺失)
  - src/services/cache.ts (无头部注释)

🔄 过期描述:
  - src/modules/user/CLAUDE.md (user.service.ts 新增了 deleteUser 方法)
  - src/auth/auth.guard.ts (INPUT 缺少 RoleService 依赖)

约束

生成约束

CLAUDE.md 文件名必须使用大写（Claude Code 约定）
不覆盖已有的项目根 CLAUDE.md（追加或合并）
模块级 CLAUDE.md 必须基于实际代码分析生成
头部注释必须基于实际 import/export 分析
不为空目录或配置目录生成 CLAUDE.md
不为第三方依赖目录生成描述（node_modules, vendor 等）

更新约束

只更新实际发生变化的文件
不修改手动编写的描述内容（通过标记区分）
向上传播仅在公共接口变化时触发
更新前必须读取现有描述

审计约束

审计模式不修改任何文件
必须生成覆盖率统计
必须标注过期描述的具体原因

范围约束

忽略隐藏目录（.git, .vscode, .idea 等）
忽略构建产物（dist/, build/, pycache/ 等）
忽略依赖目录（node_modules/, vendor/, Pods/ 等）
忽略测试目录的 CLAUDE.md 生成（测试文件仍生成头部注释）
可通过参数指定扫描范围

Skill 协作

阶段	协作 Skill	说明
开发完成后	`/devdocs-dev-workflow`	被调用：完成检查步骤中触发 --update
重构后	`/refactor`	被调用：重构完成后更新描述
项目上下文	`/devdocs-onboard`	互补：CLAUDE.md 提供模块级上下文
代码追溯	`/devdocs-sync`	互补：不同维度的代码标注
文件操作	`/git-safety`	配合：模块移动/重命名时同步更新 CLAUDE.md

参考资料

claude-md-template.md - 模块级 CLAUDE.md 模板
header-comment-examples.md - 多语言头部注释示例
update-rules.md - 层级更新传播规则