项目上下文生成器 是做什么的?
创建或更新 .claude/docs/project.md —— Claude 在每次对话中加载的精简项目参考。与面向人类读者的 README 不同,project.md 是为 Claude 编写的:密集、实诚,无营销废话。
为什么需要这个技能
.claude/docs/project.md 通过 CLAUDE.md 自动加载到每一次 Claude 对话中。当它缺失或过时时,Claude 会浪费多轮对话来重新发现技术栈、测试命令和架构。此技能自动完成这一发现过程,生成一份紧凑而准确的项目参考文件。
工作流程
第 1 步:分析代码库
执行结构化的三阶段分析来收集项目事实。为每个事实标记置信度级别:[confirmed](从源代码读取)、[inferred-high](强证据)、[inferred-low](部分证据)或 [unknown]。
参见 references/analysis-methodology.md 了解详细的工具操作、glob/grep 模式以及记录模板。
阶段 1 —— 项目元数据: 全局搜索包管理器文件、环境变量模板、CI 配置和工具链文件。提取:项目名称、语言、Python 版本、依赖项(附用途)、脚本/命令、环境变量、CI 阶段、测试标记。
阶段 2 —— 架构扫描: 全局搜索所有源代码文件。识别入口点,构建导入图,分类模块(核心/叶子层/编排器),并识别架构模式。读取源代码引用的配置文件。
阶段 3 —— 数据源与基础设施: 识别外部数据源(数据库、API、文件)、输出目标(文件、上传、API)、测试结构以及自定义异常层次结构。
第 2 步:提出澄清问题
分析完成后,向用户询问 [inferred-low] 和 [unknown] 的项目。保持聚焦——不要问你已知的事项。常见缺口:
- 项目目的: 这解决什么问题?(如果代码中不明显)
- 数据源: 什么系统将数据输入?什么接收输出?
- 部署: 这如何/在哪里运行?(本地、计划任务、云端)
如果代码库足够直接,你可能只需要 1-2 个问题或甚至不需要。
第 3 步:生成 project.md
使用以下结构写入文件。如果 .claude/docs/project.md 已经存在,在覆盖前请先与用户确认。
输出结构
生成的 project.md 必须遵循以下结构。根据项目规模调整详细程度——小项目可跳过某些章节,复杂项目可添加子章节。
# {项目名称} — 项目上下文
{一句话描述:它是什么、它做什么、关键技术。}
## 技术栈
- **{语言/运行时}** — {已知版本约束}
- **{框架}** — {用途}
- **{关键库}** — {用途}
- ...项目符号列表,工具名称加粗,注明用途
## 项目布局
```text
{带注释的目录树——每个条目一句简短说明}
```
数据流
{ASCII 示意图,显示 数据源 → 转换 → 输出 流水线}
数据源
{数据源名称}— {它提供什么}- ...包括数据库、API、本地文件等。
测试标记
{测试命令}— {它运行什么}{标记名称}— {它控制什么}
关键架构模式
- {模式名称}(
{文件}):{一句话解释} - ...仅列出值得指出的非明显模式
写作指南
- 密集优于冗长。 每一行都应该有其存在的价值。Claude 不需要动机或背景设定——只需要事实。
- 具体优于泛泛。 "运行
uv run pytest -m 'not snowflake'" 胜过 "运行排除外部依赖的测试"。 - 每个模式一句话。 架构模式应每行一个——名称、文件、解释。
- 真实命令。 从
pyproject.toml或 CI 配置中复制测试命令,而不是近似版本。 - 注释依赖项。 不要仅列出
polars—— 应写明polars —— 高性能 DataFrame。 - 数据源至关重要。 Claude 需要了解存在哪些外部系统。列出每一个数据库、API 和文件源。
- 控制在 100 行以内。 如果 project.md 内容超过约 100 行,则过于详细——应将细节移至专用文档并添加链接。
输出
将文件保存为 .claude/docs/project.md(如有需要则创建目录)。如果文件已存在,在覆盖前向用户显示差异摘要。
生成 project.md 后,检查 CLAUDE.md 是否引用了它。如果没有,建议添加如下行:
参见 [.claude/docs/project.md](.claude/docs/project.md) 了解项目特定详情(技术栈、架构、测试标记)。