Project Management Agent Skill

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。