# Project Management

> Project Management is an Agent Skill for productivity published in the cafe3310/public-agent-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

对项目结构和工作流进行管理

- Skill name: `project_management`
- Category: [Productivity](https://www.openparable.com/skill/productivity/1)
- Source: https://github.com/cafe3310/public-agent-skills/blob/HEAD/skills_archived/project-management/SKILL.md
- Repository: cafe3310/public-agent-skills (244 GitHub stars when collected)

## SKILL.md

# 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，需求，测试文档（如有必要）；
5. 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。

---

Source: https://www.openparable.com/skill/productivity/project-management-042db199 (OpenParable). Cite the canonical URL above.
