Skill - 项目管理
本技能提供了一套通用的项目管理规范和工作流程，旨在确保项目高效、规范地进行，涵盖从项目初始化、需求管理、开发、测试到部署的全过程。
关键词: project management, 任务, 需求, 文档, TODO, backlog, workshops
1.1. 何时使用本技能
如果项目章程（AGENTS.md）或用户指令中要求，则应随时使用本 Skill。具体情形包括但不限于：
- 当用户在项目中进行需求、任务或缺陷管理时；
- 当需要进行代码开发、测试、分支管理和部署操作时；
- 当用户要求整理项目结构或创建新文档时； 等等。
1.2. 如何覆盖本 Skill 的缺省描述
本 Skill 的描述可以根据具体项目需求进行调整和覆盖：
- 如果在项目章程（
AGENTS.md）中提及如覆盖 project_management 的... 部分，则应在对应部分，优先采用项目特定的描述和规范。 - 若用户要求覆盖本 Skill 的描述，请确认用户意图，并按
覆盖 project_management 的... 部分的明确描述写入项目章程。
2. 目录结构与特殊目录使用方式
为了确保项目的一致性和可维护性，推荐在仓库中采用以下标准化的 Monorepo 目录结构。
2.1. 目录结构
/ # 仓库根目录
├── .git/
├── workshops/ # 所有仓库包含的开发项目所在地
│ └── <project-name>/ # 单个项目目录
│ ├── AGENTS.md # 单个项目的章程
│ ├── TODO.md # 单个项目特定的任务列表
│ ├── docs/ # 单个项目特定的文档
│ │ ├── requirements/ # 单个项目的需求文档列表
│ │ └── specs/ # 单个项目的整体设计文档
│ └── src/ # 项目源代码
├── skills/ # 仓库特定 Skill
│ └── ...
├── local-inbox/ # 「收件箱」目录，用于用户提供文件
├── AGENTS.md # 仓库的章程
├── GEMINI.md # AGENTS.md 的符号链接（别名）
├── README.md # AGENTS.md 的符号链接（别名）
├── TODO.md # 全局的、跨项目的任务列表
├── .gitignore
└── ...部分仓库可能只包含一个项目。此时目录结构可能简化，由 AGENTS.md 确定。
2.2. 「收件箱」使用方法
如果用户需要传递非文本文件、图片、多个文件给助手，用户会将文件放置在一个约定的「收件箱」目录（默认 local-inbox/）。
助手需要定期检查此目录是否有新文件，根据文件内容和用户指令和文档对文件进行重命名，并移动到合适的归档位置（例如 docs/specs/ 或 docs/requirements/）。
3. 需求与任务管理
3.1. 文档管理
在创建任何需求、设计或其他类型的文档时，必须遵循以下规范：
- 确定位置: 根据本 Skill 和项目章程文件确定目标文档位置；
- 获取时间戳: 必须先运行
date +'%Y-%m-%d-%H-%M'命令获取当前时间； - 命名文件: 文件名必须是
YYYY-MM-DD-HH-mm-{文档名称}.md的格式，方便按时间排序和检索； - 更新 TODO: 在创建文档后，应在相应的
TODO.md任务中添加对该文档的引用链接。
在可能时，文档应链接到其「下属」文档，以形成清晰的文档层级结构。例如，主规格文档应链接到各个功能规格文档，需求文档应链接到相关的设计文档，TODO 项目应链接到对应的需求或缺陷文档。
你可以从其他 Skill 获取文档模板，以确保一致性和质量。
3.2. 任务追踪管理
为了能跟踪和持续推进用户和助手的协作，所有用户提出的任务，都要
- 记录在对应的
TODO.md文件中进行追踪； - 将
TODO.md的条目链接到更详细的文档； - 根据任务要求，编写对应的需求、缺陷、Spec 文档。 即使助手自身具备
todo类的工具，也必须遵循上述规范。
你可以从其他 Skill 获取 TODO.md 的模板。使用时，请确保包含以下关键元素：
- 状态: 任务根据其生命周期阶段，应被放置在以下列表之一：
进行中 (In Progress),待办 (TODO),阻塞 (Blocked),已完成 (Done),已搁置 (On Hold)。 - 任务单元:
- 任务 (Task): 一个宏观的目标，通常需要拆解成更小的“开发项”才能执行。 - 开发项 (Development Item): 一个具体的、可直接执行的工作单元。
- 属性: 每个任务或开发项应包含
创建日期和优先级(High, Medium, Low)。)
3.3. 产品规格管理
所有产品规格都应记录在项目目录的 docs/specs/ 目录下。这有助于保持清晰、版本化的功能文档。
- 主规格文档:
docs/specs/目录下应有一个主规格文档（例如main-spec.md），提供项目整体概述，并链接到各个功能或组件的详细规格分文档。 - 分文档: 每个主要功能或组件都应有其独立的规格文档。
- 图片资源: 与规格文档相关的图片（如设计稿、参考截图）应存放在与该文档同名的目录中。
- *示例*: docs/specs/feature-A.md 的图片资源应存放在 docs/specs/feature-A/ 目录下。
- 测试用例引用: 每个规格文档都必须明确列出并链接到相关的测试用例文档，以确保需求和验收标准一一对应。
4. 开发验证与测试
本 Skill 描述了大概的开发流程，更详细的流程应参考项目章程（AGENTS.md）中的具体描述，以及提及的其他 Skill。
4.1. TDD 模式的开发流程
开发大体上应遵循测试驱动开发 (TDD) 模式，确保代码质量和功能正确性
大体上的顺序如下：
- 确保章程、Spec 文档、需求文档齐备；
- commit 变更（文档变更）；
- 编写测试用例和文档，覆盖预期功能和边界情况；
- 进行开发、运行测试，确保所有测试通过，包括新编写的测试；
- 更新 Spec，需求，测试文档（如有必要）；
- commit 变更（代码和文档变更）。
4.2. Git 分支与部署流程
如果没有另外约定，推荐使用以下 Git 分支策略和工作流：
分支策略:
main: 主分支，始终保持可部署状态，也可以使用master作为名称。dev: 开发分支，用于集成各个功能。feat/{feat_name}: 特定功能的分支。fix/{bug_name}: 缺陷修复分支。
提交信息规范:
feat:...(新功能)fix:...(缺陷修复)docs:...(文档变更)test:...(测试相关)refactor:...(代码重构)chore:...(构建、工具等)
5. 通用要求
5.1. 理解上下文
在执行任何操作前，必须首先确定是在全局层面还是在项目层面。
- 检查用户指令:
- 如果指令明确提到项目名称 (例如 "在 my-project 项目中...")，则进入项目层面工作流。 - 如果指令模糊或涉及多个项目 (例如 "有什么高优任务？")，则优先从全局 TODO.md 开始分析。
- 读取核心文件:
- 全局层面: 读取根目录的 GEMINI.md 和 TODO.md。 - 项目层面: 读取 workshops/${project_name}/AGENTS.md 和 workshops/${project_name}/TODO.md。AGENTS.md 是理解项目内部结构和关键文件的首要信息源。)
5.2. 私钥和 Token 管理 (Secrets Management)
核心原则：严禁将任何密钥、Token、密码或包含这些信息的示例文件，包含或推送到 Git 仓库。
- 密钥文件: 所有用于本地开发的密钥都应存储在项目根目录下的
.secrets文件中，结合技术栈，在运行时选择合适的方式加载这些密钥。 - 版本控制:
.secrets文件必须被添加到.gitignore中。 - 示例文件: 可以创建
.secrets.example文件，包含密钥的占位符和说明，供开发者参考，但 绝对不能 包含真实的密钥信息。
5.3. 最佳实践
- 信任
AGENTS.md: 全局的和每个项目项目下的AGENTS.md是「事实之源」。 - 区分全局与项目: 始终清晰地区分操作是在全局层面还是项目层面，并使用对应的
TODO.md。 - 遵循命名规范: 创建文档时，严格遵循时间戳前缀的命名规范。
5.4. Emoji 使用
用户和助手约定，在文档中可使用如下的 Emoji 来标志关键信息：
- 🟩: 表示已完成、通过、成功。
- 🟥: 表示待办、有问题、未完成、需要关切。
不要随意添加其他 Emoji。