cadela-dev/ProjectAtlas

# Project Atlas 一个 Claude Code 净室文档工作流，用于将任何源码树转化为聚焦行为的镜像文档、批次报告、验证报告，以及可选的净室重建规划。 本项目旨在帮助你理解代码库的工作原理，而无需复制原始实现。你只需将源码树放入 `src/`，按顺序运行 Claude Code 提示词，工作流便会在 `docs/` 下创建结构化的文档。 ## 功能简介 Project Atlas 帮助 Claude Code 以受控批次的方式处理源码树。 它会： - 清点 `src/` 下的每一个文件 - 创建项目文件索引 - 将文件分配到各个批次中 - 为每个源文件创建一个镜像文档 - 在镜像文档中保留原始文件夹层级 - 记录可读代码、配置文件、资产文件、二进制文件、压缩文件和未知文件 - 为每个批次创建工作报告和验证报告 - 随着行为的发现，更新架构/重建说明 - 如果运行中途停止，会修复不完整的批次 - 运行最终验证步骤，确保没有遗漏 - 可选：根据文档创建通用的净室重建计划 核心理念是： ``` src/path/file.ext -> docs/_file_docs/src/path/file.ext.md ``` 每个源文件都会对应一个文档文件。 ## 注意事项 本项目**不会**： - 将源代码复制到文档中 - 充当完美的反编译器 - 保证你有检查、记录或重建任何内容的合法权限 - 自动重建项目 - 替代人工审查 - 安全地发布他人的私有/专有源码 请仅在你有权检查和记录的项目上使用它。 ## 项目结构 ``` Project Atlas/ ├── .claude/ │ ├── agents/ │ ├── rules/ │ └── skills/ ├── assignments/ │ └── .gitkeep ├── clean_rebuild_plan/ # generated later by prompt 05 ├── clean_rebuild_plan_modified/ # optional, generated later by prompts 07–08 ├── docs/ │ ├── _file_docs/ │ │ └── .gitkeep │ └── _project_index/ │ └── .gitkeep ├── prompts/ │ ├── 01_index_fresh_project.md │ ├── 02_continue_cycle.md │ ├── 03_repair_batch_consistency.md │ ├── 04_final_verify_project.md │ ├── 05_create_rebuild_plan.md │ ├── 06_master_rebuild_plan_draft.md │ ├── 07_modify_master_rebuild_plan_draft.md │ └── 08_regenerate_clean_rebuild_plan_customized.md ├── scripts/ ├── src/ │ └── .gitkeep ├── status/ │ └── .gitkeep ├── verification_reports/ │ └── .gitkeep ├── worker_reports/ │ └── .gitkeep ├── CLAUDE.md ├── README.md └── START_HERE.md ``` ## 核心规则 批次中分配的每个源文件都必须拥有一个镜像文档： ``` src/path/file.ext -> docs/_file_docs/src/path/file.ext.md ``` 这包括： - 源代码 - 配置文件 - 锁定文件 - JSON/YAML/XML - 图片 - 字体 - 归档文件 - 空文件 - 未知的二进制文件 - 压缩或混淆文件 嵌套路径必须被保留。请勿将镜像文档扁平化。 正确做法： ``` src/commands/admin/ban.js -> docs/_file_docs/src/commands/admin/ban.js.md ``` 错误做法： ``` src/commands/admin/ban.js -> docs/_file_docs/src/ban.js.md ``` ## 状态说明 `PROJECT_FILE_INDEX.md` 是动态跟踪文件。 ``` [ ] not assigned [~] assigned/in progress [x] mirrored documentation complete and verified [D] deferred with explicit reason [!] needs repair or review ``` 只有已验证的文件才应被标记为 `[x]`。 ## 提示词文件 详细的工作流提示词位于 `prompts/` 目录中。 | 提示词 | 用途 | |---|---| | `prompts/01_index_fresh_project.md` | 首次设置/索引扫描 | | `prompts/02_continue_cycle.md` | 运行单个批次 | | `prompts/03_repair_batch_consistency.md` | 在运行异常后修复缺失的镜像文档/报告 | | `prompts/04_final_verify_project.md` | 验证所有源文件、镜像文档、报告和状态的最终步骤 | | `prompts/05_create_rebuild_plan.md` | 在最终验证通过后，可选的通用净室重建规划提示词 | | `prompts/06_master_rebuild_plan_draft.md` | 将生成的重建文档整合为一个可编辑的总体规划 | | `prompts/07_modify_master_rebuild_plan_draft.md` | 创建一个单独的、可编辑的修改版总体规划 | | `prompts/08_regenerate_clean_rebuild_plan_customized.md` | 根据修改后的总体规划重新生成自定义的重建文档 | ## 辅助脚本 ``` # 可选 bootstrap/index helper python scripts/inventory_src.py --write --print-summary # Batch/report 一致性检查 python scripts/check_batch_consistency.py --latest # Compact/resume helper 摘要 python scripts/compact_resume_summary.py ``` `PROJECT_FILE_INDEX.md` 在索引开始后就是一个动态跟踪文件。在分批处理过程中，除非脚本能保留状态和说明，否则请勿盲目重新生成它。 ## 快速开始 1. 点击 **Use this template** 或克隆仓库。 2. 将你想要记录的源码树放入 `src/`。 3. 在 VS Code 中使用 Claude Code 打开该项目。 4. 运行初始索引提示词。 5. 如果需要，执行压缩。 6. 重复运行继续提示词，每次处理一个批次。 7. 仅在批次出错时使用修复提示词。 8. 当 Claude 表示所有文件处理完成后，运行最终验证。 9. 在最终验证通过后，可选择运行重建规划提示词。 ## 供 Claude Code 使用的复制粘贴提示词 本项目的设计让你**无需**每次都粘贴冗长的指令。 使用下方的简短提示词来告知 Claude Code 运行哪个工作流提示词。 ## 0. 开始之前 将你想要记录的源代码放入： ``` src/ ``` 在 VS Code / Claude Code 中打开此项目文件夹。 从项目根目录运行 Claude Code。 项目根目录应包含： ``` CLAUDE.md START_HERE.md README.md prompts/ docs/ src/ assignments/ worker_reports/ verification_reports/ status/ .claude/ ``` ## 1. 初始项目索引提示词 在处理新的源码树时使用一次。 将以下内容粘贴到 Claude Code 中： ``` Read `prompts/01_index_fresh_project.md` and execute it exactly. This is a fresh Project Atlas project. Use `src/` as the only source tree. Index every file under `src/`. Do not document source files yet. Create or update: - `docs/_project_index/PROJECT_FILE_INDEX.md` - `docs/_project_index/PROJECT_STRUCTURE.md` - `status/INDEX_STATUS.md` - `NEXT_ASSIGNMENT.md` - the first real assignment file, usually `assignments/BATCH_0001.md` Follow `.claude/rules/planner_rules.md` for batch sizing, including effective-size rules for minified, packed, binary, asset, or unusually dense files. The first assignment handoff is not complete unless both `NEXT_ASSIGNMENT.md` and the matching `assignments/BATCH_####.md` file exist. ``` 完成后，检查以下内容是否存在： ``` docs/_project_index/PROJECT_FILE_INDEX.md docs/_project_index/PROJECT_STRUCTURE.md NEXT_ASSIGNMENT.md assignments/BATCH_0001.md ``` 然后如有必要，执行压缩。 ## 2. 继续批次提示词 重复使用此提示词，直到所有文件都被记录。 将以下内容粘贴到 Claude Code 中： ``` Read `prompts/02_continue_cycle.md` and execute exactly one batch. Process the batch pointed to by `NEXT_ASSIGNMENT.md`. Do not process more than one batch. Do not reload the whole project history. Create every required mirror doc at the exact path: `src/path/file.ext` -> `docs/_file_docs/src/path/file.ext.md` Every assigned source file must have one of: - a completed mirror doc - an explicit deferred reason - an explicit error/repair reason After verification passes, do not stop until the next handoff is complete: - `NEXT_ASSIGNMENT.md` points to the next batch - the real next `assignments/BATCH_####.md` file exists - `PROJECT_FILE_INDEX.md` has current batch files marked `[x]` - `PROJECT_FILE_INDEX.md` has next batch files marked `[~]` Stop after one batch. ``` 完成后，检查： ``` worker_reports/BATCH_####_WORKER.md verification_reports/BATCH_####_VERIFICATION.md docs/_file_docs/src/ NEXT_ASSIGNMENT.md assignments/BATCH_####.md ``` 然后如有必要，执行压缩并再次运行相同的继续提示词。 ## 3. 常规重复循环 常规工作流为： ``` 1. Run initial project index prompt once. 2. Compact if needed. 3. Run continue batch prompt. 4. Compact if needed. 5. Repeat continue batch prompt until no `[ ]` or `[~]` files remain. 6. Run final verification prompt. ``` ## 4. 修复提示词 仅在批次崩溃、在批次处理中执行压缩、中途停止、遗漏镜像文档或导致报告不一致时使用。 将以下内容粘贴到 Claude Code 中： ``` Read `prompts/03_repair_batch_consistency.md` and execute it exactly. Repair the latest incomplete or inconsistent batch. Do not start a new batch. Reconcile: - the latest `assignments/BATCH_####.md` - the matching `worker_reports/BATCH_####_WORKER.md` - the matching `verification_reports/BATCH_####_VERIFICATION.md` - the required mirror docs under `docs/_file_docs/src/` - `docs/_project_index/PROJECT_FILE_INDEX.md` - `NEXT_ASSIGNMENT.md` Every assigned source file must have exactly one outcome: - mirror doc created and verified - deferred with explicit reason - failed with explicit repair reason If a mirror doc is missing, create or repair it at the exact required path: `src/path/file.ext` -> `docs/_file_docs/src/path/file.ext.md` After repair, update statuses: - verified files: `[x]` - still broken files: `[!]` - deferred files: `[D]` Stop after the repair. Do not start the next batch. ``` 修复后，重新运行继续提示词；如果你已经处理完成，则重新运行最终验证。 ## 5. 最终验证提示词 在 Claude 声称所有批次完成后使用。 将以下内容粘贴到 Claude Code 中： ``` Read `prompts/04_final_verify_project.md` and execute it exactly. This is the final completion verification. Do not trust previous batch summaries. Mechanically verify: - every real file under `src/` is listed in `PROJECT_FILE_INDEX.md` - every real file under `src/` has exactly one mirror doc - every mirror doc is at the exact depth-preserved path: `docs/_file_docs/src/path/file.ext.md` - no source files remain `[ ]` - no source files remain `[~]` - any `[D]` or `[!]` files have explicit reasons - every batch has an assignment file, worker report, and verification report - architecture synthesis files are populated - minified/packed/obfuscated files are acknowledged as such in their mirror docs Create or overwrite: `verification_reports/FINAL_PROJECT_VERIFICATION.md` If everything passes: - update `NEXT_ASSIGNMENT.md` to say `ALL FILES DOCUMENTED AND VERIFIED` - update `status/WORKFLOW_STATUS.md` - update `status/INDEX_STATUS.md` If anything fails: - create `assignments/FINAL_REPAIR.md` - list exact repair tasks - update `NEXT_ASSIGNMENT.md` to point to `assignments/FINAL_REPAIR.md` - do not perform the repairs unless explicitly asked Stop after final verification. ``` 预期通过结果： ``` verification_reports/FINAL_PROJECT_VERIFICATION.md Status: PASS ``` 如果失败，请运行修复提示词或要求 Claude 执行 `assignments/FINAL_REPAIR.md`。 ## 6. 最终修复提示词 仅在最终验证生成了 `assignments/FINAL_REPAIR.md` 时使用。 将以下内容粘贴到 Claude Code 中： ``` Read `assignments/FINAL_REPAIR.md` and execute the repair exactly. This is a final repair pass, not a normal batch. Do not process unrelated files. For each repair item: - create missing mirror docs - fix wrong mirror paths - update incorrect project index statuses - repair missing report references - update architecture synthesis docs only if the repaired file adds new verified behavior After repairs, create: `verification_reports/FINAL_REPAIR_VERIFICATION.md` Verify: - all listed repair items were completed - all repaired mirror docs exist at exact paths - `PROJECT_FILE_INDEX.md` has correct statuses - `NEXT_ASSIGNMENT.md` no longer points to unresolved repair work if all repairs passed If repair succeeds, update: `NEXT_ASSIGNMENT.md` to say: `ALL FILES DOCUMENTED AND VERIFIED` Then stop. ``` 最终修复完成后，重新运行最终验证提示词。 ## 7. 可选重建规划提示词 仅在最终验证通过后使用。 将以下内容粘贴到 Claude Code 中： ``` Read `prompts/05_create_rebuild_plan.md` and execute it exactly. Final verification has passed. Do not read `src/`. Create a generic clean-room rebuild plan using only: - `docs/_project_index/` - `docs/_file_docs/` - `verification_reports/FINAL_PROJECT_VERIFICATION.md` Do not write implementation code yet. Stop after creating `clean_rebuild_plan/`. ``` ## 8. 可选的重建计划自定义流程 提示词 `06`、`07` 和 `08` 是可选的。 如果第一个重建计划在技术上是正确的，但你想在编码前更改项目名称、移除功能、现代化技术栈、简化范围或更改实现顺序，则此自定义流程非常有用。 仅当你想在将生成的净室重建计划作为新实现的唯一事实来源之前对其进行自定义时，才使用它们。 常规的重建规划提示词 `05_create_rebuild_plan.md` 会创建： ``` clean_rebuild_plan/ ``` 该文件夹包含最初生成的重建计划。 如果你完全满意该计划的原样，则**无需**使用提示词 `06`、`07` 或 `08`。 如果你想先编辑重建方向，请使用此流程： ``` 05_create_rebuild_plan.md → creates original clean_rebuild_plan/ 06_master_rebuild_plan_draft.md → consolidates clean_rebuild_plan/ into one editable master file 07_modify_master_rebuild_plan_draft.md → copies that master into clean_rebuild_plan_modified/ 08_regenerate_clean_rebuild_plan_customized.md → regenerates customized planning files from the modified master ``` 这将同时为你提供： ``` clean_rebuild_plan/ ``` 以及： ``` clean_rebuild_plan_modified/ ``` 原始计划保持不变，而修改后的计划将成为你编辑/自定义的版本。 ## 8A. 创建总体规划草案 在提示词 `05_create_rebuild_plan.md` 创建了 `clean_rebuild_plan/` 之后使用。 将以下内容粘贴到 Claude Code 中： ``` Read `prompts/06_master_rebuild_plan_draft.md` and execute it exactly. Do not read `src/`. Use only the generated planning files inside: `clean_rebuild_plan/` Create: `clean_rebuild_plan/MASTER_REBUILD_PLAN_DRAFT.md` This master draft should consolidate the generated planning files into one editable planning document. Do not overwrite the original `clean_rebuild_plan/00–12` files. Do not create implementation code. Stop after creating the master rebuild plan draft. ``` 完成后，请审查： ``` clean_rebuild_plan/MASTER_REBUILD_PLAN_DRAFT.md ``` ## 8B. 创建可编辑的修改版总体规划 仅当你想在生成最终的自定义规划文件之前自定义重建计划时使用。 将以下内容粘贴到 Claude Code 中： ``` Read `prompts/07_modify_master_rebuild_plan_draft.md` and execute it exactly. Do not read `src/`. Use only: `clean_rebuild_plan/MASTER_REBUILD_PLAN_DRAFT.md` Create: `clean_rebuild_plan_modified/` Copy the master draft to: `clean_rebuild_plan_modified/MODIFIED_MASTER_REBUILD_PLAN_DRAFT.md` Do not generate modified 00–12 planning files yet. Stop after creating the modified master copy and README. ``` 完成后，手动编辑： ``` clean_rebuild_plan_modified/MODIFIED_MASTER_REBUILD_PLAN_DRAFT.md ``` 使用此文件来更改如下内容： * 项目名称 * 仓库名称 * 技术栈 * 项目结构 * 要移除的功能 * 要添加的功能 * 实现顺序 * 重建优先级 * 可选系统 * 风险/法律措辞 * 首轮实现 ## 8C. 重新生成自定义重建计划 在你手动编辑了以下内容后使用： ``` clean_rebuild_plan_modified/MODIFIED_MASTER_REBUILD_PLAN_DRAFT.md ``` 将以下内容粘贴到 Claude Code 中： ``` Read `prompts/08_regenerate_clean_rebuild_plan_customized.md` and execute it exactly. Do not read `src/`. Use only: `clean_rebuild_plan_modified/MODIFIED_MASTER_REBUILD_PLAN_DRAFT.md` Treat the modified master plan as the only source of truth. Regenerate the customized planning files inside: `clean_rebuild_plan_modified/` Do not overwrite the original files in: `clean_rebuild_plan/` Do not create implementation code. Stop after creating the customized planning files and regeneration summary. ``` 预期输出： ``` clean_rebuild_plan_modified/ ├── README.md ├── MODIFIED_MASTER_REBUILD_PLAN_DRAFT.md ├── 00_README.md ├── 01_REBUILD_SCOPE.md ├── 02_TECH_STACK.md ├── 03_PROJECT_STRUCTURE_PLAN.md ├── 04_DATA_AND_STATE_PLAN.md ├── 05_CORE_BOOTSTRAP_PLAN.md ├── 06_MODULE_AND_FEATURE_PLAN.md ├── 07_INTEGRATION_AND_FLOW_PLAN.md ├── 08_INTERFACE_OR_UI_PLAN.md ├── 09_SUBSYSTEM_ORDER.md ├── 10_TESTING_AND_VALIDATION_PLAN.md ├── 11_OPEN_QUESTIONS.md ├── 12_IMPLEMENTATION_ROADMAP.md └── REGENERATION_SUMMARY.md ``` 在此之后，使用： ``` clean_rebuild_plan_modified/ ``` 作为已更改/自定义重建的唯一事实来源。 ## 9. 推荐的 Claude Code 节奏 使用此节奏： ``` Initial prompt Compact Continue prompt Compact Continue prompt Compact Continue prompt Compact Repair prompt only if needed Final verification prompt Final repair if needed Final verification again ``` 在当前批次满足以下条件之前，不要让 Claude 开始新的批次： ``` assignment file mirror docs worker report verification report PROJECT_FILE_INDEX.md updates NEXT_ASSIGNMENT.md handoff ``` ## 10. 压缩、打包和混淆的文件 不要仅凭行数来判断。 某些文件可能显示为 `0` 或 `1` 行，但由于经过了压缩、打包或混淆，其体积可能依然很大。 对于这些文件，Claude 应使用： - 字节大小 - 文件扩展名 - 文件路径 - import/require 线索 - 可见字符串 - exports/module 形态 - 配置引用 - 模型引用 - 副作用 - 不确定性说明 针对这些文件的镜像文档应明确指出行为是在何时被推断出来的。 ## 11. 注意事项 请勿要求 Claude 执行以下操作： ``` Document everything in one pass. Read the whole project history every batch. Skip assets. Skip binaries. Flatten mirror docs. Trust line count for minified files. Start a new batch before the previous batch is verified. Declare completion without final verification. ``` 请使用提示词文件和本指南进行操作。 ## 贡献 欢迎积极贡献。 良好的贡献类型包括： - 更清晰的提示词 - 更安全的净室规则 - 更好的分批逻辑 - 更强的最终验证 - 更好的修复处理 - 改进的辅助脚本 - 更好的 README/文档 请勿提交私有源代码、购买的源代码、来自私有项目的生成镜像文档、机密信息、token 或凭据。 ## 许可证 MIT

标签：AI辅助分析, Claude Code, Clean-room, Subfinder, 云资产清单, 代码文档, 工作流自动化, 文档生成, 逆向工具, 逆向工程, 防御加固