project-management

name	project_management
description	对项目结构和工作流进行管理
author	github/cafe3310
license	Apache-2.0

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. 文档管理

在创建任何需求、设计或其他类型的文档时，必须遵循以下规范：

1. 确定位置: 根据本 Skill 和项目章程文件确定目标文档位置；
2. 获取时间戳: 必须先运行 date +'%Y-%m-%d-%H-%M' 命令获取当前时间；
3. 命名文件: 文件名必须是 YYYY-MM-DD-HH-mm-{文档名称}.md 的格式，方便按时间排序和检索；
4. 更新 TODO: 在创建文档后，应在相应的 TODO.md 任务中添加对该文档的引用链接。

在可能时，文档应链接到其「下属」文档，以形成清晰的文档层级结构。例如，主规格文档应链接到各个功能规格文档，需求文档应链接到相关的设计文档，TODO 项目应链接到对应的需求或缺陷文档。

你可以从其他 Skill 获取文档模板，以确保一致性和质量。

3.2. 任务追踪管理

为了能跟踪和持续推进用户和助手的协作，所有用户提出的任务，都要

1. 记录在对应的 TODO.md 文件中进行追踪；
2. 将 TODO.md 的条目链接到更详细的文档；
3. 根据任务要求，编写对应的需求、缺陷、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) 模式，确保代码质量和功能正确性

大体上的顺序如下：

1. 确保章程、Spec 文档、需求文档齐备；
2. commit 变更（文档变更）；
3. 编写测试用例和文档，覆盖预期功能和边界情况；
4. 进行开发、运行测试，确保所有测试通过，包括新编写的测试；
5. 更新 Spec，需求，测试文档（如有必要）；
6. commit 变更（代码和文档变更）。

4.2. Git 分支与部署流程

如果没有另外约定，推荐使用以下 Git 分支策略和工作流：

分支策略:

• main: 主分支，始终保持可部署状态，也可以使用 master 作为名称。
• dev: 开发分支，用于集成各个功能。
• feat/{feat_name}: 特定功能的分支。
• fix/{bug_name}: 缺陷修复分支。

提交信息规范:

• feat: ... (新功能)
• fix: ... (缺陷修复)
• docs: ... (文档变更)
• test: ... (测试相关)
• refactor: ... (代码重构)
• chore: ... (构建、工具等)

5. 通用要求

5.1. 理解上下文

在执行任何操作前，必须首先确定是在全局层面还是在项目层面。

1. 检查用户指令:

   • 如果指令明确提到项目名称 (例如 "在 my-project 项目中...")，则进入项目层面工作流。
   • 如果指令模糊或涉及多个项目 (例如 "有什么高优任务？")，则优先从全局 TODO.md 开始分析。

2. 读取核心文件:

   • 全局层面: 读取根目录的 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。