Project Index – Layered CLAUDE.md System

自动生成和维护大型项目的层次化 CLAUDE.md 索引系统。

📌 推荐使用 pi-cli

project-index 和 pi-cli 功能已统一。推荐使用 pi CLI 作为统一入口：

# 等效命令对照
node scripts/module-analyzer.js --stale  →  pi module analyze --llm --stale
node scripts/test-fix.js                 →  pi test fix --llm
node scripts/dashboard.js --open         →  pi ui

详见 pi-cli SKILL.md

⛔ 严禁操作 (CRITICAL – 必读)

2026-01-22 事故记录：执行 git checkout HEAD -- tests/ 和 git checkout HEAD -- js/，导致用户一整天的手动工作（100+ 文件）永久丢失，无法恢复。

以下操作必须先询问用户确认，否则绝对禁止执行：

1. git checkout HEAD -- / git checkout -- <path> — 会永久丢弃未提交修改
2. git reset --hard — 会永久丢弃所有未提交修改
3. git clean -fd — 会永久删除未跟踪文件
4. git stash drop / git stash clear — 会永久删除 stash
5. 任何批量删除文件的操作 (rm -rf, find -delete 等)

批量任务进度保护：每完成一批任务后，必须提交或提醒用户提交。

功能清单

AI 交互指引

主动询问

完成批量任务后，应主动询问用户：

任务完成。是否打开 Dashboard 查看详细状态？
→ 运行: node scripts/dashboard.js --open
→ 访问: http://localhost:3008

任务前检查

执行文档/测试任务前，先检查状态：

node scripts/check-stale.js --stale-only --json

根据输出决定处理范围。

触发场景

1. 新项目入驻 — 用户说”帮我分析这个项目”、”生成文档”
2. 遗留项目理解 — 用户说”这个代码库怎么组织的”
3. 代码修改后 — 检测到核心模块变更，提醒更新文档
4. 测试维护 — 用户说”生成测试”、”修复测试”
5. 审计需求 — 用户说”检查安全问题”、”代码审计”
6. 提交前验收 — 用户说”验收门禁”、”检查变更”、”提交验证”

前置依赖

核心概念

三层架构

project/CLAUDE.md           # Layer 1: 概览 + 模块索引
    ↓
src/modules/auth/CLAUDE.md  # Layer 2: 模块详情 + 子模块索引
    ↓
src/modules/auth/jwt/CLAUDE.md  # Layer 3: 实现细节

智能覆盖策略

不是每个目录都需要独立 CLAUDE.md：

• 大目录 (≥5 文件或 ≥200 行) → 必须有独立 CLAUDE.md
• 小目录 + 父目录有 CLAUDE.md → 由父目录覆盖
• 小目录 + 父目录无 CLAUDE.md → 孤儿，需关注

详见 docs/coverage.md

层级依赖排序

批量生成时按目录深度从深到浅处理：

js/agents/core/sandbox/system  → 先生成
js/agents/core/sandbox         → 后生成
js/agents/core                 → 再后
js/agents                      → 最后

确保父目录生成时可引用子目录的 CLAUDE.md。

AUDIT.md 同策略

代码审计 (code-audit.js) 采用相同策略：

• 大目录生成独立 AUDIT.md
• 小目录由父目录审计覆盖
• 审计提示词包含未独立审计的小子目录代码

快速开始

# 1. 扫描项目
node scripts/scan.js

# 2. 生成 CLAUDE.md
node scripts/generate.js --auto

# 3. 安装 hooks
node scripts/hook.js init

# 4. 启动 Dashboard
node scripts/dashboard.js --open

常用命令

详见 docs/commands.md

快速参考：

node scripts/module-analyzer.js          # 日常维护
node scripts/module-analyzer.js --all    # 全量处理
node scripts/check-stale.js --stale-only # 过期检测
node scripts/test-fix.js                 # 修复测试错误
node scripts/dashboard.js --open         # Web UI

工作流

新项目

1. hook.js init – 安装 hooks + 创建配置
2. scan.js – 分析结构
3. generate.js --auto – 生成文档
4. 开始开发

遗留项目

1. scan.js – 理解结构
2. hook.js init – 安装配置
3. generate.js --auto – 生成文档
4. module-analyzer.js – 初始审计
5. 按需调整

代码修改后

修改模块代码后，必须检查并更新对应的 CLAUDE.md 和 AUDIT.md：

1. 检查 CLAUDE.md

   • 内容需要更新 → 修改文档内容
   • 内容仍然准确 → touch CLAUDE.md 更新时间戳

2. 检查 AUDIT.md

   • 新增安全问题 → 补充到 Issues 列表
   • 问题已修复 → 使用 audit-archive.js 归档
   • 内容仍然准确 → touch AUDIT.md 更新时间戳

3. 验证状态

   node scripts/check-stale.js <module-path> --stale-only
   node scripts/audit-status.js <module-path>
   

重要：即使没有实质性改动，也必须 touch 文件以更新时间戳，否则 stale 检测会持续报告该模块过期。

详细文档

硬约束（MUST READ）

执行以下功能前，必须先读取对应的最佳实践文档：

约束级别：

• ✅ MUST READ – 执行功能前必须读取对应文档
• ✅ MUST FOLLOW – 必须遵循文档中的硬约束规则（MUST/MUST NOT）
• ⚠️ 违反后果 – 可能导致数据丢失、测试失败、审计问题遗漏

AI 执行检查清单：

1. 识别用户请求的功能类型
2. 检查是否有对应的必读文档
3. 读取并理解文档中的硬约束规则
4. 执行功能时严格遵循约束
5. 完成后验证是否符合最佳实践

配置

创建 .stale-config.json：

{
  "include": ["js/agents/**"],
  "ignore": ["tests/**", "docs/**"],
  "features": { "doc": true, "audit": true, "kanban": true, "testAnalysis": true },
  "concurrency": 6
}

测试追踪

测试状态与 CLAUDE.md/AUDIT.md 统一追踪：

# 检查测试覆盖状态
node scripts/check-stale.js --type=test --stale-only

# 检查所有类型（doc + audit + test）
node scripts/check-stale.js --type=all --stale-only

# 刷新测试映射
node scripts/test-mapper.js

# 查看模块测试详情
node scripts/test-view.js js/agents/core

测试状态类型：

• missing – 模块无测试覆盖
• stale – 源码已修改但测试未更新
• fresh – 测试与源码同步

详见 docs/testing.md

与 Codex 集成

更新父目录时注入小子目录上下文：

context=$(node generate.js --prompt-context --module js/agents/ingest)

codex-wrapper - <<EOF
更新 js/agents/ingest/CLAUDE.md

$context
EOF

Kanban API

审计任务自动创建到 Kanban：

export KANBAN_URL=http://127.0.0.1:3007/api/v1

未运行 Kanban 服务时静默跳过。

依赖分析系统

构建文件级依赖图，支持影响分析和 stale 传播。

依赖图构建

# 扫描 js/agents 构建依赖图
node scripts/dependency-graph.js --module js/agents

# 查询单文件依赖
node scripts/dependency-graph.js --check shared/index.js

# JSON 输出
node scripts/dependency-graph.js --json

输出文件：.dep-graph.json

影响分析

分析变更文件的下游影响范围：

# 分析指定文件
node scripts/impact-analyzer.js shared/utils/logger.js core/event-bus.js

# 分析 git 变更
node scripts/impact-analyzer.js --since HEAD~5
node scripts/impact-analyzer.js --staged

# JSON 输出
node scripts/impact-analyzer.js --since HEAD~3 --json

Stale 传播

将 stale 状态沿依赖图向下游传播：

# 自动检测 + 传播
node scripts/stale-propagate.js

# 指定变更文件
node scripts/stale-propagate.js --changed core/event-bus.js

# 包含测试重跑列表
node scripts/stale-propagate.js --changed core/event-bus.js --tests

# 调整传播深度（默认 2）
node scripts/stale-propagate.js --depth 3

输出示例：

Direct stale: 2 files
Propagated stale: 45 files (L1: 12, L2: 33)
Tests to re-run: 40 files

典型工作流

# 1. 构建/更新依赖图
node scripts/dependency-graph.js --module js/agents

# 2. 代码修改后，分析影响
node scripts/impact-analyzer.js --staged

# 3. 检查 stale 传播
node scripts/stale-propagate.js --tests

# 4. 运行受影响的测试
node scripts/test-affected.js --staged

智能测试修复（100+ 错误场景）

当有大量测试失败时，智能排序修复顺序：

# 分析失败测试的优先级
node scripts/test-prioritize.js --from-file test-results.json

# 输出：
# Phase 1 - Root causes: shared/utils/logger.js (261 依赖)
# Phase 2 - Independent: 可并行修复的批次
# Phase 3 - Leaf nodes: 最后修复

修复策略：

1. 先修 root cause — 被依赖最多的文件，一个修复解决多个错误
2. 并行修独立集 — 无依赖关系的文件可以 60 开并发
3. 最后修叶子节点 — 依赖链末端的文件

# 按优先级运行测试
node scripts/test-affected.js --staged --prioritized

验收门禁

提交前验证 git 变更，确保代码质量。

验证流程

1. 扫描变更 — 获取 git diff 中的 JS/TS 文件
2. DAG 分组 — 按依赖图分组，相关文件一起验证
3. 并发验证 — 四维检查：lint、测试覆盖、功能测试、安全审计
4. 结果汇总 — 标记通过/失败文件
5. 选择性提交 — 仅提交通过验证的文件

使用方式

# 预览变更文件分组
node scripts/acceptance-gate.js --dry-run

# 运行验证
node scripts/acceptance-gate.js

# 验证并自动提交通过的文件
node scripts/acceptance-gate.js --commit

# 跳过部分检查
node scripts/acceptance-gate.js --skip-lint --skip-security

# 调整并发
node scripts/acceptance-gate.js --concurrency=8

安全约束

• 禁止 git checkout、git reset 等危险操作
• 仅提交通过验证的文件
• 失败文件只标记，不自动修改

⚠️ 禁止的错误模式

测试修复和代码生成时必须避免的反模式。

详见 docs/anti-patterns.md