初始化架构师（自适应版）

不暴露参数；内部自适应三档：快速摘要 / 模块扫描 / 深度补捞。保证每次运行可增量更新、可续跑，并输出覆盖率报告与下一步建议。

一、通用约束

• 不修改源代码；仅生成/更新文档与 .claude/index.json。
• 忽略规则获取策略：
  1. 优先读取项目根目录的 .gitignore 文件
  2. 如果 .gitignore 不存在，则使用以下默认忽略规则：node_modules/**,.git/**,.github/**,dist/**,build/**,.next/**,__pycache__/**,*.lock,*.log,*.bin,*.pdf,*.png,*.jpg,*.jpeg,*.gif,*.mp4,*.zip,*.tar,*.gz
  3. 将 .gitignore 中的忽略模式与默认规则合并使用
• 对大文件/二进制只记录路径，不读内容。

二、分阶段策略（自动选择强度）

1. 阶段 A：全仓清点（轻量）
   • 以多次 Glob 分批获取文件清单（避免单次超限），做：
     • 文件计数、语言占比、目录拓扑、模块候选发现（package.json、pyproject.toml、go.mod、Cargo.toml、apps/、packages/、services/、cmd/ 等）。
   • 生成 模块候选列表，为每个候选模块标注：语言、入口文件猜测、测试目录是否存在、配置文件是否存在。
2. 阶段 B：模块优先扫描（中等）
   • 对每个模块，按以下顺序尝试读取（分批、分页）：
     • 入口与启动：main.ts/index.ts/cmd/*/main.go/app.py/src/main.rs 等
     • 对外接口：路由、控制器、API 定义、proto/openapi
     • 依赖与脚本：package.json scripts、pyproject.toml、go.mod、Cargo.toml、配置目录
     • 数据层：schema.sql、prisma/schema.prisma、ORM 模型、迁移目录
     • 测试：tests/**、__tests__/**、*_test.go、*.spec.ts 等
     • 质量工具：eslint/ruff/golangci 等配置
   • 形成"模块快照"，只抽取高信号片段与路径，不粘贴大段代码。
3. 阶段 C：深度补捞（按需触发）
   • 触发条件（满足其一即可）：
     • 仓库整体较小（文件数较少）或单模块文件数较少；
     • 阶段 B 后仍无法判断关键接口/数据模型/测试策略；
     • 根或模块 CLAUDE.md 缺信息项。
   • 动作：对目标目录追加分页读取，补齐缺项。

注：如果分页/次数达到工具或时间上限，必须提前写出部分结果并在摘要中说明"到此为止的原因"和"下一步建议扫描的目录列表"。

三、产物与增量更新

1. 写入根级 CLAUDE.md

   • 如果已存在，则在顶部插入/更新 变更记录 (Changelog)。
   • 根级结构（精简而全局）：

     • 项目愿景

     • 架构总览

     • ✨ 新增：模块结构图（Mermaid）

       • 在"模块索引"表格上方，根据识别出的模块路径，生成一个 Mermaid graph TD 树形图。

       • 每个节点应可点击，并链接到对应模块的 CLAUDE.md 文件。

       • 示例语法：

         graph TD
             A["(根) 我的项目"] --> B["packages"];
             B --> C["auth"];
             B --> D["ui-library"];
             A --> E["services"];
             E --> F["audit-log"];
         
             click C "./packages/auth/CLAUDE.md" "查看 auth 模块文档"
             click D "./packages/ui-library/CLAUDE.md" "查看 ui-library 模块文档"
             click F "./services/audit-log/CLAUDE.md" "查看 audit-log 模块文档"
         

     • 模块索引（表格形式）

     • 运行与开发

     • 测试策略

     • 编码规范

     • AI 使用指引

     • 变更记录 (Changelog)

2. 写入模块级 CLAUDE.md

   • 放在每个模块目录下，结构建议：
     • ✨ 新增：相对路径面包屑
       • 在每个模块 CLAUDE.md 的最顶部，插入一行相对路径面包屑，链接到各级父目录及根 CLAUDE.md。
       • 示例（位于 packages/auth/CLAUDE.md）： [根目录](../../CLAUDE.md) > [packages](../) > **auth**
     • 模块职责
     • 入口与启动
     • 对外接口
     • 关键依赖与配置
     • 数据模型
     • 测试与质量
     • 常见问题 (FAQ)
     • 相关文件清单
     • 变更记录 (Changelog)

3. .claude/index.json

   • 记录：当前时间戳（通过参数提供）、根/模块列表、每个模块的入口/接口/测试/重要路径、扫描覆盖率、忽略统计、是否因上限被截断（truncated: true）。

四、覆盖率与可续跑

• 每次运行都计算并打印：
  • 估算总文件数、已扫描文件数、覆盖百分比；
  • 每个模块的覆盖摘要与缺口（缺接口、缺测试、缺数据模型等）；
  • 被忽略/跳过的 Top 目录与原因（忽略规则/大文件/时间或调用上限）。
• 将"缺口清单"写入 index.json，下次运行时优先补齐缺口（断点续扫）。

五、结果摘要（打印到主对话）

• 根/模块 CLAUDE.md 新建或更新状态；
• 模块列表（路径+一句话职责）；
• 覆盖率与主要缺口；
• 若未读全：说明"为何到此为止"，并列出推荐的下一步（例如"建议优先补扫：packages/auth/src/controllers、services/audit/migrations"）。

六、时间格式与使用

• 路径使用相对路径；
• 时间信息：使用通过命令参数提供的时间戳，并在 index.json 中写入 ISO-8601 格式。
• 不要手动编写时间信息，使用提供的时间戳参数确保时间准确性。