code-self-describe

Code Self-Description

Generate and maintain a self-describing structure for the codebase, leveraging Claude Code's hierarchical loading mechanism to achieve progressive context understanding.

Language Rules

Support questions in Chinese and English
Always reply in Chinese
CLAUDE.md file content uses Chinese
Source file header comments use Chinese

Trigger Conditions

The user needs to add AI-friendly code descriptions for the project
The user needs to update descriptions after code changes
The user needs to check description coverage and accuracy
Keywords: "self-describe", "module description", "generate CLAUDE.md", "self-describe"

Core Concepts

Self-Similar Architecture

Leverage Claude Code'shierarchical loading mechanism(when a file is found, the CLAUDE.md in its directory is automatically loaded) to improve the AI's code understanding through a three-layer self-describing structure:

项目根 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

When the AI searches to a fifth-layer file, the first four layers of CLAUDE.md have already been automatically loaded, giving an extremely clear understanding of the entire module.

Three-Layer Description System

Layer	Carrier	Content
Project level	Root CLAUDE.md	Module list, global constraints
Module level	Directory CLAUDE.md	Status, logic, constraints, business domain list
File level	Source code header comments	INPUT、OUTPUT、POS

Boundary with keel Traceability

Self-descriptionstays in the code, keel traceabilitydoes not stay in the code. The criterion is:if the code loses this piece of information, can it still be correctly interpreted and maintained.

	Self-description (INPUT/OUTPUT/POS)	keel traceability
Answers what	What this module does, who it depends on	Which requirement this piece of code was written for
For maintainers without keel context	Useful—can be understood without any external system	Is noise—does not know what `AC-001` is, where to look it up, or whether it still exists
After keel is lost	Remains effective as usual	Becomes a pointer to the void
Carrier	File header comments	Documentation-side traceability matrix（`<repository>@<sha>`), ⛔ does not go into code

⛔ Must not add new @requirement / @satisfies / @verifies / @testcase annotations. Existing ones are left in place and not cleaned up.

Operating Modes

/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                 → 审计：检查描述新鲜度和准确性

Mode Comparison

Mode	Scan Scope	Generate CLAUDE.md	Update header comments	User Confirmation
init	Whole project/specified module	✅ Create new	✅ Add new	✅ Module by module
update	Changed files (git diff)	✅ Update existing	✅ Update changes	Automatic for low risk
audit	All projects	❌ Report only	❌ Report only	❌

Skipped by default under shell topology

This skill's artifacts (module-level CLAUDE.md + source file header comments) are written inside the code directory. The motivation of the shell topology is precisely to keep private artifacts out of the code repository, and the two directly conflict.

Criterion taken from handshake workspace_context.capabilities.code_metadata_write_policy：explicit_opt_in → skipped by default, only --force-code-docs executes;unrestricted → as usual. ⛔ Do not read mode to branch on its own—file header comments are written into the source file itself, and enumerating by write strategy would erroneously let them pass, so this is listed as a separate capability.

Skipped by default, outputs ℹ️ explaining the reason, does not error
Only --force-code-docs explicitly enabled. Before enabling, confirm via AskUserQuestion: "These files will enter <each code_root>; if that repository will be public, please confirm this is acceptable"
Code roots taken from handshake workspace_context.code_roots, contract see shared/constraints.md §3

Smart detection flow

检测项目是否已有模块级 CLAUDE.md
        │
        ├── 无 → 自动进入 init 模式
        │
        └── 有 → 检测是否有代码变更
                │
                ├── 有未同步变更 → 建议 update 模式
                └── 无变更 → 建议 audit 模式

Init mode

Workflow

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. 生成描述清单报告

Module-level CLAUDE.md template

For detailed templates and examples see templates/claude-md-template.md

# <模块名>

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

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

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

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

Source file header comment format

For multilingual examples see templates/header-comment-examples.md

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

Comments must be placed at the very beginning of the file(before the import statements), because AI loads files starting from the head.

Update mode

Workflow

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

Update propagation rules

For detailed rules see templates/update-rules.md

Propagate upward only when public interfaces change(internal refactoring does not trigger it)
Markers distinguish automatic/manual content（ markers denote automatically generated parts)
Do not modify manually written descriptions

Audit mode

Audit content

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

Audit report format (terminal 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 依赖)

Constraints

Generation constraints

The CLAUDE.md filename must be uppercase(Claude Code convention)
Do not overwrite an existing project-root CLAUDE.md(append or merge)
Module-level CLAUDE.md must be generated based on actual code analysis
Header comments must be based on actual import/export analysis
Do not generate CLAUDE.md for empty directories or configuration directories

Update constraints

Only update files that actually changed
Do not modify manually written description content(distinguished via markers)
Upward propagation is triggered only when public interfaces change
Must read the existing description before updating

Audit constraints

Audit mode does not modify any files
Must generate coverage statistics
Must indicate the specific reason a description is outdated

Scope constraints

Ignore hidden directories(.git, .vscode, .idea, etc.)
Ignore build artifacts（dist/, build/, pycache/ etc.)
Ignore dependency directories(node_modules/, vendor/, Pods/, etc.)
Ignore CLAUDE.md generation for test directories(test files still generate header comments)

Skill collaboration

Stage	Collaborating Skill	Description
After development is complete	`/dev-workflow`	Called: triggers --update during the completion check step
After refactoring	`/refactor`	Called: updates the description after refactoring is complete
Project context	`/onboard`	Complementary: CLAUDE.md provides module-level context
Code traceability	`/sync`	Complementary: code annotation from different dimensions
File operations	`/git-safety`	Coordinate: synchronously update CLAUDE.md when modules are moved/renamed

References

claude-md-template.md - Module-level CLAUDE.md template
header-comment-examples.md - Multi-language header comment examples
update-rules.md - Hierarchical update propagation rules

About this skill

Language Rules

Trigger Conditions

Core Concepts

Self-Similar Architecture

Three-Layer Description System

Boundary with keel Traceability

Operating Modes

Mode Comparison

Skipped by default under shell topology

Smart detection flow

Init mode

Workflow

Module-level CLAUDE.md template

Source file header comment format

Update mode

Workflow

Update propagation rules

Audit mode

Audit content

Audit report format (terminal output)

Constraints

Generation constraints

Update constraints

Audit constraints

Scope constraints

Skill collaboration

References