acquire-codebase-knowledge

获取代码库知识

在 docs/codebase/ 中生成七份内容充实文档，涵盖高效推进该项目所需的一切信息。只记录可从文件或终端输出中验证的内容 — 绝不推断或假设。

输出契约（必需）

完成前，以下所有条件必须为真：

1. docs/codebase/ 中恰好存在这些文件：STACK.md、STRUCTURE.md、ARCHITECTURE.md、CONVENTIONS.md、INTEGRATIONS.md、TESTING.md、CONCERNS.md。
2. 每条论断都可追溯到源文件、配置或终端输出。
3. 未知项标记为 [TODO]；依赖意图的决策标记为 [ASK USER]。
4. 每份文档都包含简短的“证据”列表，列出具体文件路径。
5. 最终回复包含编号的 [ASK USER] 问题以及意图与现实之间的偏差。

工作流

复制并跟踪此清单：

- [ ] Phase 1: Run scan, read intent documents
- [ ] Phase 2: Investigate each documentation area
- [ ] Phase 3: Populate all seven docs in docs/codebase/
- [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] items

聚焦领域模式

如果用户提供了聚焦领域（例如：“仅架构”或“测试与关注点”）：

1. 始终完整运行第 1 阶段。
2. 先完整完成聚焦领域的文档。
3. 对于尚未分析的非聚焦文档，保留必需章节，并将未知项标记为 [TODO]。
4. 最终输出前，仍要对全部七份文档运行第 4 阶段验证循环。

第 1 阶段：扫描并阅读意图

1. 从目标项目根目录运行扫描脚本：

   python3 "$SKILL_ROOT/scripts/scan.py" --output docs/codebase/.codebase-scan.txt
   

   其中 $SKILL_ROOT 是 skill 文件夹的绝对路径。适用于 Windows、macOS 和 Linux。

   快速开始： 如果你已内联路径：

   python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt
   

2. 搜索 PRD、TRD、README、ROADMAP、SPEC、DESIGN 文件并阅读它们。

3. 在阅读任何源代码之前，先总结项目声明的意图。

第 2 阶段：调查

使用扫描输出为七个模板逐一回答问题。加载 references/inquiry-checkpoints.md 获取每个模板的完整问题列表。

如果技术栈不明确（存在多个清单文件、不熟悉的文件类型、没有 package.json），加载 references/stack-detection.md。

第 3 阶段：填充模板

将 assets/templates/ 中的每个模板复制到 docs/codebase/。按此顺序填写：

1. STACK.md — 语言、运行时、框架、所有依赖
2. STRUCTURE.md — 目录布局、入口点、关键文件
3. ARCHITECTURE.md — 分层、模式、数据流
4. CONVENTIONS.md — 命名、格式化、错误处理、导入
5. INTEGRATIONS.md — 外部 API、数据库、认证、监控
6. TESTING.md — 框架、文件组织、模拟策略
7. CONCERNS.md — 技术债、缺陷、安全风险、性能瓶颈

对于任何无法从代码中确定的内容，使用 [TODO]。若正确答案需要团队意图，使用 [ASK USER]。

第 4 阶段：验证、修复、核实

定稿前运行此强制验证循环：

1. 对照 references/inquiry-checkpoints.md 验证每份文档。
2. 对于每条非平凡论断，确认至少存在一条证据引用。
3. 如果任何必需章节缺失或缺乏支持：

• 修复文档。
• 重新运行验证。

4. 重复，直到全部七份文档通过。

然后展示全部七份文档的摘要，将每个 [ASK USER] 项列为编号问题，并突出显示第 1 阶段发现的任何意图与现实之间的偏差。

验证通过标准：

• 没有缺乏支持的论断。
• 没有空的必需章节。
• 未知项使用 [TODO]，而不是假设。
• 团队意图缺口明确标记为 [ASK USER]。

---

注意事项

Monorepo： 根 package.json 可能没有源码——检查是否存在 workspaces、packages/ 或 apps/ 目录。每个 workspace 可能有独立的依赖和约定。分别梳理每个子包。

过时的 README： README 通常描述的是预期架构，而非当前架构。在将任何 README 中的说法当作事实之前，先与实际文件结构交叉核对。

TypeScript 路径别名： tsconfig.json 的 paths 配置意味着 @/foo 这类导入不会直接映射到文件系统。在记录结构之前，先把别名映射到真实路径。

生成/编译产物： 绝不要记录来自 dist/、build/、generated/、.next/、out/ 或 __pycache__/ 的模式。这些是产物——只记录源码约定。

.env.example 揭示必需配置： 密钥永远不会被提交。读取 .env.example、.env.template 或 .env.sample 来发现必需的环境变量。

devDependencies ≠ 生产技术栈： 只有 dependencies（或等价项，例如 [tool.poetry.dependencies]）会在生产环境中运行。将 linter、formatter 和测试框架单独记录为开发工具。

测试中的 TODO ≠ 生产债务： test/、tests/、__tests__/ 或 spec/ 中的 TODO 是覆盖率缺口，而非生产技术债务。在 CONCERNS.md 中将它们区分开来。

高变更频率的文件 = 脆弱区域： 在近期 git 历史中出现最多的文件修改率最高，很可能存在隐藏的复杂性。务必在 CONCERNS.md 中标注它们。

---

反模式

❌ 不要	✅ 而应
“使用 Clean Architecture，包含 Domain/Data 层。”（当此类目录并不存在时）	只陈述目录结构实际展示的内容。
“这是一个 Next.js 项目。”（未检查 package.json）	先检查 dependencies。陈述实际存在的内容。
根据 dbUrl 这样的变量名猜测数据库	检查清单文件中的 pg、mysql2、mongoose、prisma 等。
将 dist/ 或 build/ 的命名模式记录为约定	只记录源文件。

---

增强的扫描输出部分

scan.py 脚本现在除了原始输出外，还会生成以下部分：

• CODE METRICS — 文件总数、按语言统计的代码行数、最大的文件（复杂性信号）
• CI/CD PIPELINES — 检测到的 GitHub Actions、GitLab CI、Jenkins、CircleCI 等
• CONTAINERS & ORCHESTRATION — Docker、Docker Compose、Kubernetes、Vagrant 配置
• SECURITY & COMPLIANCE — Snyk、Dependabot、SECURITY.md、SBOM、安全策略
• PERFORMANCE & TESTING — 基准测试配置、性能分析标记、负载测试工具

在 Phase 2 中使用这些部分来为调查问题提供信息，并识别特定工具的模式。

---

随附资源

资源	何时加载
scripts/scan.py	Phase 1 — 最先运行，在阅读任何代码之前（需要 Python 3.8+）
references/inquiry-checkpoints.md	Phase 2 — 加载以获得各模板的调查问题
references/stack-detection.md	Phase 2 — 仅在技术栈不明确时
assets/templates/STACK.md	Phase 3 步骤 1
assets/templates/STRUCTURE.md	Phase 3 步骤 2
assets/templates/ARCHITECTURE.md	Phase 3 步骤 3
assets/templates/CONVENTIONS.md	Phase 3 步骤 4
assets/templates/INTEGRATIONS.md	Phase 3 步骤 5
assets/templates/TESTING.md	Phase 3 步骤 6
assets/templates/CONCERNS.md	Phase 3 步骤 7

模板使用模式：

• 默认模式：仅完成每个模板中的“核心部分（必需）”。
• 扩展模式：仅当仓库复杂性足以证明其合理时，才添加可选部分。