setup-project-md

设置 PROJECT.md

概述

一次性设置：将代码库证据与用户提供的产品背景结合起来，在根目录生成一个 PROJECT.md，说明这个项目是什么以及各部分如何协同。除非用户明确要求重新生成或更新文件，否则不要将此视为持续维护技能。

输出

• 只写入一个文件：仓库根目录下的 PROJECT.md。
• 如果 PROJECT.md 已存在，询问一次是覆盖、合并/更新还是中止。不要默默覆盖。

工作流

1. 梳理代码库

检查足够的信息，以准确描述系统：

• 根目录文档：README.md、架构说明、部署文档、环境示例（仅记录名称——绝不复制机密值）。
• 清单和工具链：包管理器、工作区、应用/包布局、CI、Docker、基础设施入口点。
• 运行时结构：入口点、路由、主要领域/模块、数据存储、队列、外部服务。
• 产品界面：Web 应用、API、CLI、工作进程、管理端、文档站点——仅列出实际存在的部分。

优先采用仓库中的证据，而非营销说法。明确标注推断内容。

2. 收集用户背景

询问代码无法完全说明的产品事实。集中提问，涵盖：

• 使命/解决的问题以及非目标。
• 目标用户和主要用例。
• 商业模式或分发方式（如适用）。
• 当前阶段（原型、Beta、生产）及已知限制。
• 重要历史、所有权信息，或 Agent 经常忽略的决策。
• 在线产品、设计稿或问题跟踪器链接（可选）。

如果用户一开始就提供了简要说明，请使用这些信息，只询问尚缺的关键内容。如果用户拒绝访谈，则继续操作并标注假设。

3. 核对代码与叙述

• 结构、技术栈和命令以代码和配置为准。
• 意图、受众、路线图和业务背景以用户输入为准。
• 如果发现矛盾，且会影响概述，则指出并与用户确认解决方式。

4. 编写 PROJECT.md

使用 references/template.md。填写适用的章节；省略空白章节。质量标准：

• 新 Agent 阅读一次后，就能理解项目目的、产品界面、代码布局以及如何运行。
• 区分产品意图与实现结构图。
• 提供具体路径和命令，避免含糊的架构长篇说明。
• 不包含机密信息；环境变量仅列名称。
• 对未知内容和进行中的工作如实说明。

5. 链接到 AGENTS.md（有条件）

PROJECT.md 创建后：

1. 仅检查根目录下的 AGENTS.md。
2. 如果不存在，则跳过链接操作。不要创建 AGENTS.md。
3. 如果存在，且尚未添加链接，则添加指向 PROJECT.md 的明确链接：
   • 优先放在现有的索引、文档或相关文档章节中。
   • 否则添加简短章节，例如 ## 项目文档，并附上一项： - [PROJECT.md](PROJECT.md) — 产品与代码库概述
   • 不要将完整概述复制到 AGENTS.md。
   • 保留 AGENTS.md 中无关的内容。

6. 交付

• 确认写入的路径。
• 简要总结：用一行说明项目用途、主要界面，以及 AGENTS.md 是已更新还是已跳过。
• 除非用户要求，否则不要提交更改。

隔离性

此技能独立运行。不要提及、链接到或依赖其他技能。仅参考仓库文件、用户输入以及此技能的 references/。

不在范围内

• 替换 README.md 或编写完整的架构 ADR。
• 在梳理代码库时实现功能或重构。
• 在 AGENTS.md 缺失时创建该文件。
• 除非用户要求再次运行设置流程，否则不进行定期审查。