Skills
skills/mksteady/mkskills/project-index

project-index

SKILL.md

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 等)

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

功能清单

功能 脚本 说明
文档生成 generate.js 生成/更新 CLAUDE.md
代码审计 code-audit.js 生成 AUDIT.md，检测安全问题
过期检测 check-stale.js 检测文档/审计/测试是否过期
依赖图构建 dependency-graph.js 构建文件级依赖图，检测循环依赖
影响分析 impact-analyzer.js 分析变更文件的下游影响范围
stale 传播 stale-propagate.js 依赖传播 stale 状态 + 测试重跑列表
测试优先级 test-prioritize.js 智能排序：root cause 优先 + 并行批次
智能测试 test-affected.js 只运行受变更影响的测试
测试映射 test-mapper.js 源码↔测试映射，生成 .test-map.json
测试生成 test-generator.js 批量生成缺失测试
测试修复 test-fix.js 并发修复测试错误
审计修复 audit-fix.js 并发修复审计问题
验收门禁 acceptance-gate.js DAG 分组验证 git 变更，仅提交通过文件
Dashboard dashboard.js Web UI (http://localhost:3008)

AI 交互指引

主动询问

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

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

任务前检查

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

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

根据输出决定处理范围。

触发场景

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

前置依赖

依赖 类型 用途
codeagent-wrapper 必需 LLM 调用
kanban 可选 审计任务自动创建

核心概念

三层架构

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 检测会持续报告该模块过期。

详细文档

文档 内容
docs/commands.md 常用命令详解
docs/coverage.md 智能覆盖率策略、批量任务发现
docs/dashboard.md Web UI 仪表盘详解
docs/scripts.md 所有脚本参考
docs/config.md 配置文件说明
docs/testing.md 测试工具链详解
docs/anti-patterns.md ⚠️ 禁止的错误模式
docs/dag-scheduling.md DAG 依赖调度（目录层级处理）
docs/batch-best-practices.md 批量任务最佳实践

硬约束（MUST READ）

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

功能 必读文档 说明
test-fix, test-generator docs/testing.md, docs/anti-patterns.md 测试修复和生成的最佳实践与禁止模式
audit-fix, code-audit docs/audit-best-practices.md 审计修复流程、问题分类、归档规范
module-analyzer --llm docs/batch-best-practices.md 批量 LLM 任务的并发设置、checkpoint、rate limit 处理
dependency-graph, impact-analyzer, stale-propagate, test-prioritize docs/dependency-best-practices.md 依赖分析、影响范围、stale 传播、测试优先级排序

约束级别：

  • ✅ 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

Weekly Installs
3
Repository
mksteady/mkskills
GitHub Stars
9
First Seen
Feb 27, 2026
Security Audits
Gen Agent Trust HubWarn
SocketFail
SnykPass
Installed on
opencode3
claude-code3
github-copilot3
codex3
kimi-cli3
gemini-cli3