codemap

Codemap

我能做什么

分析整个代码库，并在 .planning/codebase/ 中创建 7 份全面的文档：

• STACK.md - 技术、依赖项和配置
• INTEGRATIONS.md - 第三方提供方、API、数据库和身份验证提供方
• ARCHITECTURE.md - 系统模式、分层和数据流
• STRUCTURE.md - 目录布局、关键位置和命名约定
• CONVENTIONS.md - 代码风格、模式和错误处理
• TESTING.md - 框架、结构、模拟和覆盖率
• CONCERNS.md - 技术债务、Bug、安全和性能问题

何时使用我

在以下情况下使用此技能：

• 引导新开发者快速了解代码库
• 规划新功能，并全面了解现有模式
• 了解代码约定，然后再进行修改
• 识别技术债务和需要关注的领域
• 记录项目的当前状态

工作原理

此技能会执行四轮重点分析。运行环境支持时，使用并行的文件读取和文件写入工作器。如果没有合适的工作器，则在当前上下文中按顺序执行相同的分析：

1. 技术 → 分析技术栈和集成 → STACK.md、INTEGRATIONS.md
2. 架构 → 分析模式和结构 → ARCHITECTURE.md、STRUCTURE.md
3. 质量 → 分析约定和测试 → CONVENTIONS.md、TESTING.md
4. 关注事项 → 识别技术债务和问题 → CONCERNS.md

每轮分析：

• 针对相应重点探索代码库
• 使用 $SKILL_PATH/templates/ 中的模板
• 直接将文档写入 .planning/codebase/
• 仅返回确认信息（不返回文档内容）

协调程序：

• 创建 .planning/codebase/ 目录
• 仅在有合适工作器时并行运行四轮分析
• 否则在当前上下文中按顺序运行这些分析
• 收集确认信息
• 验证所有文档均已创建
• 提交代码库地图（如果已配置）

流程

范围和运行环境

接受可选参数 --paths <p1,p2,...>，用于生成增量地图。使用前验证相对于仓库的路径前缀：拒绝绝对路径、.. 组件和 shell 元字符（;、反引号、$、&、|、<、>）。如果没有提供有效路径，则停止并要求用户更正范围；不要默默将范围扩大到整个仓库。将相同的规范化范围传递给每个映射器以及按顺序执行的每一轮分析。不要将未经检查的输入插入 shell 命令。

所有分析日期占位符均使用当前实际日期。对于范围内的刷新，保留范围外已记录的信息，并说明重新检查了哪些前缀。

仅当运行环境支持文件读取和文件写入工作器时，才使用并行 Agent。不要假设 explore Agent 能写入文件，也不要将浏览器 Agent 用作代码映射器。如果没有合适的工作器，则在当前上下文中按顺序执行四轮重点分析，并使用相同的范围和模板。不要要求使用 GSD 专用 SDK 命令或 Agent 类型。

第 1 步：检查现有地图

如果 .planning/codebase/ 已存在，请提示：

.planning/codebase/ already exists. What's next?
1. Refresh - Delete existing and remap codebase
2. Update - Keep existing, only update specific documents
3. Skip - Use existing codebase map as-is

第 2 步：创建结构

创建输出目录：

mkdir -p .planning/codebase

第 3 步：执行四轮重点分析

仅当运行环境支持文件读取和文件写入工作器时，才并行执行这些分析。否则，在当前上下文中按顺序执行。并行工作器是可选项，并非必需。每轮分析都必须收到经过验证的范围、当前日期以及 $SKILL_PATH/templates/ 中对应的模板路径。以下示例说明了任务分配，并非强制要求的 API 参数名称。并行工作器运行期间，不要重复其探索工作或编写其负责的文档。

技术 Agent：

agent_type: explore
description: Map codebase tech stack
prompt: |
	Focus: tech

	Analyze this codebase for technology stack and external integrations.

	Write these documents to .planning/codebase/:
	- STACK.md - Languages, runtime, frameworks, dependencies, configuration
	- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks

	Use the templates from map-codebase skill. Explore thoroughly.
	Write documents directly. Return confirmation only.

架构 Agent：

agent_type: explore
description: Map codebase architecture
prompt: |
	Focus: arch

	Analyze this codebase architecture and directory structure.

	Write these documents to .planning/codebase/:
	- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
	- STRUCTURE.md - Directory layout, key locations, naming conventions

	Use the templates from map-codebase skill. Explore thoroughly.
	Write documents directly. Return confirmation only.

质量 Agent：

agent_type: explore
description: Map codebase conventions
prompt: |
	Focus: quality

	Analyze this codebase for coding conventions and testing patterns.

	Write these documents to .planning/codebase/:
	- CONVENTIONS.md - Code style, naming, patterns, error handling
	- TESTING.md - Framework, structure, mocking, coverage

	Use the templates from map-codebase skill. Explore thoroughly.
	Write documents directly. Return confirmation only.

关注事项 Agent：

agent_type: explore
description: Map codebase concerns
prompt: |
	Focus: concerns

	Analyze this codebase for technical debt, known issues, and areas of concern.

	Write this document to .planning/codebase/:
	- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas

	Use the templates from map-codebase skill. Explore thoroughly.
	Write document directly. Return confirmation only.

第 4 步：验证输出

等待每个映射器完成。检查预期的 7 份文档是否全部存在，并且每份都超过 20 行；仅有文件名并不代表成功。报告缺失、内容过短或失败的输出，并在宣布完成前修复。检查日期是否为当前日期，以及范围限定的输出是否保留了未受影响的信息。

ls -la .planning/codebase/
wc -l .planning/codebase/*.md

第 5 步：检查密钥并选择性提交

在展示或提交文档之前，扫描是否意外复制了凭据。列出配置路径和环境变量名称，不要列出密钥值。不要读取 .env 内容或映射所用的凭据文件。若有可用的仓库密钥扫描器，请使用它。最低限度的补充检查如下：

rg -l '(sk-[A-Za-z0-9]{20,}|gh[pousr]_[A-Za-z0-9]{36,}|AKIA[A-Z0-9]{16}|xox[baprs]-[A-Za-z0-9-]+|-----BEGIN.*PRIVATE KEY)' .planning/codebase/*.md

此命令只会打印文件名，不会打印匹配到的密钥值。无匹配项的退出状态属于正常情况；扫描器出错则不代表扫描干净。如果发现匹配项，请停止操作、删除相关内容，并在继续前重新检查。模式匹配不能证明所有密钥都已清除；还要检查从日志和配置中复制的摘录。

如果检查通过、.planning/ 未被 git 忽略，并且用户希望提交：

git add .planning/codebase/*.md
git commit -m "docs: map existing codebase

- STACK.md - Technologies and dependencies
- ARCHITECTURE.md - System design and patterns
- STRUCTURE.md - Directory layout
- CONVENTIONS.md - Code style and patterns
- TESTING.md - Test structure
- INTEGRATIONS.md - External services
- CONCERNS.md - Technical debt and issues"

第 6 步：总结

提供完成情况总结：

Codebase mapping complete.

Created .planning/codebase/:
- STACK.md ([N] lines) - Technologies and dependencies
- ARCHITECTURE.md ([N] lines) - System design and patterns
- STRUCTURE.md ([N] lines) - Directory layout and organization
- CONVENTIONS.md ([N] lines) - Code style and patterns
- TESTING.md ([N] lines) - Test structure and practices
- INTEGRATIONS.md ([N] lines) - External services and APIs
- CONCERNS.md ([N] lines) - Technical debt and issues

Next steps:
- Review documents: cat .planning/codebase/STACK.md
- Use these as reference when planning features
- Update as codebase evolves

模板

模板位于 $SKILL_PATH/templates/：

• STACK.md.template - 技术栈
• INTEGRATIONS.md.template - 外部集成
• ARCHITECTURE.md.template - 系统架构
• STRUCTURE.md.template - 目录结构
• CONVENTIONS.md.template - 编码约定
• TESTING.md.template - 测试模式
• CONCERNS.md.template - 技术问题

每个 Agent 都会读取相应的模板，并根据代码库探索结果填写内容。

Agent 指南

作为映射器 Agent 启动时：

探索命令

辅助工具：如有 fd，请使用；否则改用 find

# Define finder helper (fd if available, otherwise find)
_finder() { command -v fd >/dev/null 2>&1 && fd "$@" || find "$@"; }
_rg() { command -v rg >/dev/null 2>&1 && rg "$@" || grep -r "$@"; }

技术重点：

# Package manifests
cat package.json pyproject.toml Cargo.toml go.mod 2>/dev/null

# Config files
ls -la *.config.* tsconfig.json 2>/dev/null

# Find SDK/API imports
_rg "import.*stripe|import.*supabase|import.*aws" src/ 2>/dev/null | head -50

架构重点：

# Directory structure (fd is faster and ignores node_modules/.git by default)
_finder -t d . | head -50

# Entry points
_finder -t f "index.*" "main.*" "app.*" src/ app/ 2>/dev/null | head -20

# Import patterns
_rg "^import" src/ 2>/dev/null | head -100

质量重点：

# Linting/formatting config
cat .eslintrc* .prettierrc* biome.json 2>/dev/null

# Test files
_finder -t f "\.test\." "\.spec\." 2>/dev/null | head -30

问题重点：

# TODO/FIXME comments
_rg "TODO|FIXME|HACK|XXX" src/ 2>/dev/null | head -50

# Large files (potential complexity)
_finder -t f "\.ts$" -e "\.tsx$" src/ 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -20

关键规则

1. 直接编写文档 —— 使用 Write 工具，不要返回文档内容
2. 始终包含文件路径 —— 每项发现都需要包含用反引号括起来的文件路径
3. 使用模板 —— 严格按照模板结构填写
4. 全面细致 —— 阅读实际文件，不要猜测
5. 仅返回确认信息 —— 回复约 10 行，并包含文件路径和行数
6. 跳过提交 —— 由协调器处理 Git 操作

灵感来源

此技能的灵感来自并改编自 glittercowboy/get-shit-done，具体参考了其 map-codebase 工作流和 gsd-codebase-mapper Agent。