wshobson/scan

scan 是做什么的？

扫描代码库以生成 project-doc.md 和 AGENTS.md 文件。适用于引导新代理驱动的仓库、在架构变更后刷新项目文档，或进行增量扫描以检测漂移。首次使用运行完整扫描，后续运行智能增量扫描。支持 understand-anything + context-mode，不可用时回退到原生工具。仅在检测到架构变更且经人工确认后才更新 AGENTS.md。

工作流

该技能按以下步骤执行：

1. 检测运行环境：检查是否支持 understand-anything 工具及其 context-mode。
2. 执行扫描：
   • 首次运行：完整扫描整个代码库，分析所有文件结构、依赖关系和架构。
   • 后续运行：增量扫描，仅检测自上次扫描以来发生的变化。
3. 生成文档：
   • 创建/更新 project-doc.md：包含项目概述、架构、模块说明和关键文件索引。
   • 创建/更新 AGENTS.md：包含给 AI 代理的指导说明，如开发惯例、关键文件位置和操作约束。
4. 安全更新：仅在检测到架构变更时，提示用户确认后才更新 AGENTS.md。

使用场景

• 引导新仓库：当为新项目或现有项目初始化 AI 代理支持时，使用 scan 生成初始文档。
• 架构变更后：在重构、添加主要模块或更改构建系统后，运行 scan 刷新文档。
• 漂移检测：定期运行 scan 的增量模式，快速识别文档与实际代码之间的差异。

环境兼容性

平台	支持状态	说明
Claude Code	✅	优先使用 understand-anything
Cursor	✅	支持上下文模式
Codex	✅	回退到原生工具
其他	⚠️	自动检测并回退

输出文件

文件	用途	何时更新
project-doc.md	项目架构和模块文档	每次扫描后更新
AGENTS.md	给 AI 代理的指导	仅在架构变更且经人工确认后更新

命令示例

# 在当前目录运行扫描
scan

# 强制完整扫描（忽略增量缓存）
scan --full

# 仅检测漂移（不更新文件）
scan --check

# 指定扫描深度（1=仅顶层文件，3=深层递归）
scan --depth 3

环境变量

变量名	用途	默认值
SKIP_AGENTS_UPDATE	设置为 true 跳过 AGENTS.md 更新提示	false
SCAN_DEPTH	扫描目录深度	5
SCAN_EXCLUDE	排除的目录/文件模式（逗号分隔）	node_modules,.git,dist

注意事项

• AGENTS.md 的更新需要人工确认，以避免意外覆盖代理指令。
• 增量扫描使用文件修改时间戳进行变化检测，因此在 git checkout 或 rebase 后可能触发完整扫描。
• 在非常庞大的代码库中，首次完整扫描可能需要较长时间；建议使用排除选项忽略非必要目录。