需要全面技术分析代码库时，用分阶段侦察与综合报告解决架构…

当用户提供代码库目录并要求技术总览、架构文档、代码审计、架构评审或仓库总结时，按五个阶段生成面向工程师的 markdown 综合分析报告。

适用场景

解决思路

1. 定位为资深软件架构师和技术写作者，对代码库执行全面的技术分析，并产出面向工程师的详细 markdown 文档。
2. 接收用户提供的目录路径，将其作为要分析的代码库根目录。
3. 将综合分析写入 `{TARGET_DIR}/{REPO_NAME}_COMPREHENSIVE_ANALYSIS.md`：`{TARGET_DIR}` 是用户提供的根目录，`{REPO_NAME}` 是仓库/项目名（从目录名或项目 manifest 推导）。
4. 按顺序执行各阶段，不跳过阶段；逐步思考并保持有条理。
5. 阶段 1：侦察（广泛扫描），目标是建立代码库心智地图，不读取每个文件。
6. 阶段 1-1：列出顶层目录结构（2-3 层深），记录目录布局和命名约定。
7. 阶段 1-2：识别关键 manifest/config 文件并优先阅读。包 manifest：`package.json`、`Cargo.toml`、`go.mod`、`pyproject.toml`、`pom.xml`、`build.gradle`、`build.gradle.kts`、`Gemfile`、`*.csproj`、`Podfile`、`*.xcodeproj/project.pbxproj`、`Package.swift` 等。构建/CI 配置：`Makefile`、`Dockerfile`、`docker-compose.yml`、`.github/workflows/*`、`ci.yml`、`bin/ci`、`Jenkinsfile`、`turbo.json`、`nx.json`、`lerna.json`、`fastlane/Fastfile`。配置文件：`tsconfig.json`、`.eslintrc.*`、`.env.example`、`webpack.config.*`、`vite.config.*`、`detekt.yml`、`.rubocop.yml`、`.swiftlint.yml`、`checkstyle.xml`、`.editorconfig`。文档：`README.md`、`CONTRIBUTING.md`、`ARCHITECTURE.md`、`docs/` 文件夹。
8. 阶段 1-3：识别多模块/monorepo 结构（如适用）：映射 packages、modules、services、targets、shared libraries 及其关系。
9. 阶段 1-4：基于文件扩展名、imports 和 manifests 编目代码库中使用的语言与框架。
10. 阶段 2：架构深入分析，目标是理解系统结构及组件如何交互。
11. 阶段 2-1：识别入口点：`main.*`、`index.*`、`app.*`、`server.*`、`AppDelegate.*`、`Application.*`、路由定义、CLI 入口、Android activity/fragment 入口、iOS view controller 层级。
12. 阶段 2-2：追踪核心应用流程：端到端跟随最多 5 条关键路径（例如 API 请求从 route → controller → service → data layer → response，UI 交互从用户事件 → 状态管理 → 渲染，后台任务生命周期）。如果还有更多流程，记录它们并引用读者可自行追踪的文件。
13. 阶段 2-3：映射内部模块/packages 之间的依赖图，记录哪些组件依赖哪些组件。
14. 阶段 2-4：识别架构模式：微服务、单体、事件驱动、六边形/整洁架构、MVC、CQRS 等。
15. 阶段 2-5：检查数据层：数据库 schemas/migrations、ORM 用法、数据模型、缓存策略。
16. 阶段 2-6：检查 API 表面：REST、GraphQL、gRPC、WebSocket、IPC 或 SDK 接口定义；记录 auth 模式、protocol buffers 或 API contracts。
17. 阶段 3：质量与模式评估，目标是评估工程实践和代码质量。
18. 阶段 3-1：测试：检查测试目录结构、使用的框架、测试模式（unit、integration、e2e）、覆盖率配置、fixture/mock 策略。
19. 阶段 3-2：错误处理：错误如何传播？是否有集中式错误处理？日志策略是什么？
20. 阶段 3-3：类型安全与验证：类型安全严格度（例如 compiler flags、strict modes、lint rules）、运行时验证（schema libraries、contract enforcement）、null safety，以及输入/输出 schema 强制。
21. 阶段 3-4：安全态势：auth/authz 模式、secrets management、输入清洗、依赖漏洞（如果存在 lockfile）。
22. 阶段 3-5：代码模式：扫描命名约定、模块组织、抽象层次和代码重复方面的一致性。
23. 阶段 4：基础设施与运维，目标是理解软件如何构建、部署和运行。
24. 阶段 4-1：构建系统：构建工具、bundling、编译步骤、monorepo 任务编排。
25. 阶段 4-2：CI/CD pipeline：检查 workflow 文件中的 test、lint、build、deploy 阶段。
26. 阶段 4-3：部署模型：containers、serverless、PaaS、static hosting、app store 分发、embedded/firmware 交付；如存在则检查基础设施即代码（Terraform、Pulumi、CDK）。
27. 阶段 4-4：可观测性：logging、metrics、tracing、monitoring、alerting 配置。
28. 阶段 4-5：环境管理：dev、staging、prod 等环境如何区分。
29. 阶段 5：综合与文档生成，目标是编译发现到输出文档。
30. 阶段 5-1：使用 `references/output-template.md` 中的输出模板确定文档结构。
31. 阶段 5-2：将最终分析写入上文 Output 中描述的输出路径。
32. 执行规则 1：先读后写。在完成阶段 1-4 之前不要生成文档。
33. 执行规则 2：引用具体文件。每个论断都应引用实际文件路径（例如 `src/api/routes.ts`）；绝不做没有证据的泛泛观察。
34. 执行规则 3：诚实说明未知项。如果无法确定某事项（例如编译/压缩后的部分，或无法访问的服务），要明确说明。
35. 执行规则 4：深度优先于广度。对任何非平凡代码库都不可能读完每个文件；聚焦入口点、核心业务逻辑和架构边界；跳过生成代码、vendored dependencies 和 boilerplate。
36. 执行规则 5：使用 ASCII 图说明架构和流程；保持简单可读。
37. 执行规则 6：按比例分配精力。大约 60% 精力用于阶段 2-3（架构与质量），20% 用于阶段 1（侦察），20% 用于阶段 4（基础设施）。
38. 执行规则 7：分节写输出文件。增量构建 markdown 文件——每完成一个主要章节就写入该章节，而不是试图在一次操作中写完整个文档。
39. 执行规则 8：文件大小启发式。在大型目录中决定读什么时，优先级为：入口点 > 配置 > 核心领域逻辑 > 工具函数 > 测试 > 生成代码。
40. 执行规则 9：只读分析。不要修改、创建或删除目标代码库中的任何文件；唯一写入的文件是输出分析文档。
41. 执行规则 10：大型代码库启发式。对于 monorepo 或超过 500 个文件的代码库，聚焦最重要的前 2-3 个模块/服务，而不是尝试完整覆盖；在 Executive Summary 中说明范围限制。

适用边界 · 注意事项

• 只做快速代码搜索或单文件审查时，不应使用该技能；应使用标准编辑器工具。
• 需要修改、创建或删除代码库文件，或需要重构/修复 bug 时，不适用，因为该技能只做只读分析并生成分析文档。
• 目标代码只有编译/压缩产物且无法访问源码或关键服务时，不适合期望得到无遗漏的确定性结论；应在报告中明确未知项。