project_management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill - 项目管理

Skill - Project Management

本技能提供了一套通用的项目管理规范和工作流程，旨在确保项目高效、规范地进行，涵盖从项目初始化、需求管理、开发、测试到部署的全过程。

关键词: project management, 任务, 需求, 文档, TODO, backlog, workshops

This skill provides a set of universal project management specifications and workflows, designed to ensure projects proceed efficiently and in a standardized manner, covering the entire process from project initialization, requirement management, development, testing to deployment.

Keywords: project management, task, requirement, document, TODO, backlog, workshops

1.1. 何时使用本技能

1.1. When to Use This Skill

如果项目章程（

AGENTS.md

）或用户指令中要求，则应随时使用本 Skill。具体情形包括但不限于：

当用户在项目中进行需求、任务或缺陷管理时；
当需要进行代码开发、测试、分支管理和部署操作时；
当用户要求整理项目结构或创建新文档时；等等。

Use this Skill whenever required by the project charter (

AGENTS.md

) or user instructions. Specific scenarios include but are not limited to:

When the user is managing requirements, tasks, or defects in the project;
When code development, testing, branch management, and deployment operations are needed;
When the user requests to organize the project structure or create new documents; and so on.

1.2. 如何覆盖本 Skill 的缺省描述

1.2. How to Override the Default Description of This Skill

本 Skill 的描述可以根据具体项目需求进行调整和覆盖：

如果在项目章程（
```
AGENTS.md
```
）中提及如
```
覆盖 project_management 的 ... 部分
```
，则应在对应部分，优先采用项目特定的描述和规范。
若用户要求覆盖本 Skill 的描述，请确认用户意图，并按
```
覆盖 project_management 的 ... 部分
```
的明确描述写入项目章程。

The description of this Skill can be adjusted and overridden according to specific project requirements:

If the project charter (
```
AGENTS.md
```
) mentions something like "Override the ... section of project_management", the project-specific descriptions and specifications should be prioritized in the corresponding section.
If the user requests to override the description of this Skill, confirm the user's intent and write the explicit description in the project charter as "Override the ... section of project_management".

2. Directory Structure and Usage of Special Directories

为了确保项目的一致性和可维护性，推荐在仓库中采用以下标准化的 Monorepo 目录结构。

To ensure project consistency and maintainability, it is recommended to adopt the following standardized Monorepo directory structure in the repository.

2.1. 目录结构

2.1. Directory Structure

/                              # 仓库根目录
├── .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

确定。

/                              # Repository root directory
├── .git/
├── workshops/                   # Location of all development projects included in the repository
│   └── <project-name>/            # Single project directory
│       ├── AGENTS.md              # Charter for the single project
│       ├── TODO.md                # Project-specific task list
│       ├── docs/                  # Project-specific documents
│       │   ├── requirements/        # Requirement document list for the single project
│       │   └── specs/               # Overall design documents for the single project
│       └── src/                   # Project source code
├── skills/                      # Repository-specific Skills
│   └── ...
├── local-inbox/                 # "Inbox" directory for users to provide files
├── AGENTS.md                    # Repository charter
├── GEMINI.md                    # Symbolic link (alias) to AGENTS.md
├── README.md                    # Symbolic link (alias) to AGENTS.md
├── TODO.md                      # Global, cross-project task list
├── .gitignore
└── ...

Some repositories may contain only one project. In this case, the directory structure can be simplified, determined by

AGENTS.md

2.2. 「收件箱」使用方法

2.2. Usage of the "Inbox" Directory

如果用户需要传递非文本文件、图片、多个文件给助手，用户会将文件放置在一个约定的「收件箱」目录（默认

local-inbox/

）。

助手需要定期检查此目录是否有新文件，根据文件内容和用户指令和文档对文件进行重命名，并移动到合适的归档位置（例如

docs/specs/

或

docs/requirements/

）。

If the user needs to send non-text files, images, or multiple files to the assistant, the user will place the files in a agreed "Inbox" directory (default

local-inbox/

The assistant needs to regularly check this directory for new files, rename the files based on their content, user instructions, and documents, and move them to the appropriate archive location (such as

docs/specs/

docs/requirements/

3. 需求与任务管理

3. Requirement and Task Management

3.1. 文档管理

3.1. Document Management

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

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

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

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

When creating any requirement, design, or other type of document, the following specifications must be followed:

Determine Location: Confirm the target document location according to this Skill and the project charter file;
Get Timestamp: Must first run the command
```
date +'%Y-%m-%d-%H-%M'
```
to get the current time;
Name the File: The file name must follow the format
```
YYYY-MM-DD-HH-mm-{document-name}.md
```
to facilitate sorting and retrieval by time;
Update TODO: After creating the document, add a reference link to this document in the corresponding
```
TODO.md
```
task.

Whenever possible, documents should link to their "subordinate" documents to form a clear document hierarchy. For example, the main specification document should link to each functional specification document, requirement documents should link to related design documents, and TODO items should link to corresponding requirement or defect documents.

You can obtain document templates from other Skills to ensure consistency and quality.

3.2. 任务追踪管理

3.2. Task Tracking Management

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

记录在对应的
```
TODO.md
```
文件中进行追踪；
将
```
TODO.md
```
的条目链接到更详细的文档；
根据任务要求，编写对应的需求、缺陷、Spec 文档。即使助手自身具备
```
todo
```
类的工具，也必须遵循上述规范。

你可以从其他 Skill 获取

TODO.md

的模板。使用时，请确保包含以下关键元素：

状态: 任务根据其生命周期阶段，应被放置在以下列表之一：

进行中 (In Progress)

待办 (TODO)

阻塞 (Blocked)

已完成 (Done)

已搁置 (On Hold)

。

任务单元:
- 任务 (Task): 一个宏观的目标，通常需要拆解成更小的“开发项”才能执行。
- 开发项 (Development Item): 一个具体的、可直接执行的工作单元。
属性: 每个任务或开发项应包含
```
创建日期
```
和
```
优先级
```
(High, Medium, Low)。)

To track and continuously advance collaboration between the user and the assistant, all tasks proposed by the user must:

Be recorded in the corresponding
```
TODO.md
```
file for tracking;
Link entries in
```
TODO.md
```
to more detailed documents;
Write corresponding requirement, defect, and Spec documents according to task requirements. Even if the assistant itself has
```
todo
```
-type tools, the above specifications must be followed.

You can obtain the

TODO.md

template from other Skills. When using it, ensure it includes the following key elements:

Status: Tasks should be placed in one of the following lists according to their lifecycle stage:
```
In Progress
```
,
```
TODO
```
,
```
Blocked
```
,
```
Done
```
,
```
On Hold
```
.
Task Units:
- Task: A macro goal that usually needs to be broken down into smaller "Development Items" for execution.
- Development Item: A specific, directly executable work unit.
Attributes: Each task or development item should include
```
Creation Date
```
and
```
Priority
```
(High, Medium, Low).)

3.3. 产品规格管理

3.3. Product Specification Management

所有产品规格都应记录在项目目录的

docs/specs/

目录下。这有助于保持清晰、版本化的功能文档。

主规格文档:
```
docs/specs/
```
目录下应有一个主规格文档（例如
```
main-spec.md
```
），提供项目整体概述，并链接到各个功能或组件的详细规格分文档。
分文档: 每个主要功能或组件都应有其独立的规格文档。
图片资源: 与规格文档相关的图片（如设计稿、参考截图）应存放在与该文档同名的目录中。
- 示例:
```
docs/specs/feature-A.md
```
  的图片资源应存放在
```
docs/specs/feature-A/
```
  目录下。
测试用例引用: 每个规格文档都必须明确列出并链接到相关的测试用例文档，以确保需求和验收标准一一对应。

All product specifications should be recorded in the

docs/specs/

directory of the project directory. This helps maintain clear, versioned functional documents.

Main Specification Document: There should be a main specification document (e.g.,
```
main-spec.md
```
) in the
```
docs/specs/
```
directory, providing an overall project overview and linking to detailed specification sub-documents for each feature or component.
Sub-documents: Each major feature or component should have its own independent specification document.
Image Resources: Images related to specification documents (such as design drafts, reference screenshots) should be stored in a directory with the same name as the document.
- Example: Image resources for
```
docs/specs/feature-A.md
```
  should be stored in the
```
docs/specs/feature-A/
```
  directory.
Test Case References: Each specification document must explicitly list and link to related test case documents to ensure a one-to-one correspondence between requirements and acceptance criteria.

4. 开发验证与测试

4. Development Verification and Testing

本 Skill 描述了大概的开发流程，更详细的流程应参考项目章程（

AGENTS.md

）中的具体描述，以及提及的其他 Skill。

This Skill describes a general development process; for more detailed processes, refer to the specific descriptions in the project charter (

AGENTS.md

) and other mentioned Skills.

4.1. TDD 模式的开发流程

4.1. TDD Development Workflow

开发大体上应遵循测试驱动开发 (TDD) 模式，确保代码质量和功能正确性

大体上的顺序如下：

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

Development should generally follow the Test-Driven Development (TDD) pattern to ensure code quality and functional correctness

The general sequence is as follows:

Ensure the charter, Spec documents, and requirement documents are complete;
Commit changes (document changes);
Write test cases and documents covering expected functions and boundary conditions;
Perform development, run tests, and ensure all tests pass, including newly written tests;
Update Spec, requirement, and test documents if necessary;
Commit changes (code and document changes).

4.2. Git 分支与部署流程

4.2. Git Branch and Deployment Workflow

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

分支策略:

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

提交信息规范:

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

Unless otherwise agreed, the following Git branching strategy and workflow are recommended:

Branching Strategy:

```
main
```
: Main branch, always in a deployable state;
```
master
```
can also be used as the name.
```
dev
```
: Development branch for integrating various features.
```
feat/{feat_name}
```
: Branch for a specific feature.
```
fix/{bug_name}
```
: Branch for defect fixes.

Commit Message Specifications:

```
feat: ...
```
(New feature)
```
fix: ...
```
(Defect fix)
```
docs: ...
```
(Document changes)
```
test: ...
```
(Testing-related)
```
refactor: ...
```
(Code refactoring)
```
chore: ...
```
(Build, tools, etc.)

5. 通用要求

5. General Requirements

5.1. 理解上下文

5.1. Understand Context

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

检查用户指令:
- 如果指令明确提到项目名称 (例如 "在
```
my-project
```
  项目中...")，则进入项目层面工作流。
- 如果指令模糊或涉及多个项目 (例如 "有什么高优任务？")，则优先从全局
  TODO.md
  开始分析。
读取核心文件:
- 全局层面: 读取根目录的
```
GEMINI.md
```
  和
```
TODO.md
```
  。
- 项目层面: 读取
```
workshops/${project_name}/AGENTS.md
```
  和
```
workshops/${project_name}/TODO.md
```
  。
```
AGENTS.md
```
  是理解项目内部结构和关键文件的首要信息源。)

Before performing any operation, it is necessary to first determine whether it is at the global level or project level.

Check User Instructions:
- If the instruction explicitly mentions a project name (e.g., "In the
```
my-project
```
  project..."), enter the project-level workflow.
- If the instruction is ambiguous or involves multiple projects (e.g., "What are the high-priority tasks?"), start analysis from the global
  TODO.md
  first.
Read Core Files:
- Global Level: Read the root directory's
```
GEMINI.md
```
  and
```
TODO.md
```
  .
- Project Level: Read
```
workshops/${project_name}/AGENTS.md
```
  and
```
workshops/${project_name}/TODO.md
```
  .
```
AGENTS.md
```
  is the primary source of information for understanding the project's internal structure and key files.)

5.2. 私钥和 Token 管理 (Secrets Management)

5.2. Secrets Management (Private Keys and Tokens)

核心原则：严禁将任何密钥、Token、密码或包含这些信息的示例文件，包含或推送到 Git 仓库。

密钥文件: 所有用于本地开发的密钥都应存储在项目根目录下的
```
.secrets
```
文件中，结合技术栈，在运行时选择合适的方式加载这些密钥。
版本控制:
```
.secrets
```
文件必须被添加到
```
.gitignore
```
中。
示例文件: 可以创建
```
.secrets.example
```
文件，包含密钥的占位符和说明，供开发者参考，但 绝对不能 包含真实的密钥信息。

Core Principle: Strictly prohibit including or pushing any keys, tokens, passwords, or sample files containing such information to the Git repository.

Secret Files: All keys used for local development should be stored in the
```
.secrets
```
file in the project root directory, and loaded using an appropriate method at runtime according to the tech stack.
Version Control: The
```
.secrets
```
file must be added to
```
.gitignore
```
.
Sample Files: You can create a
```
.secrets.example
```
file containing placeholders and instructions for keys for developers' reference, but must never contain real key information.

5.3. 最佳实践

5.3. Best Practices

信任
AGENTS.md
: 全局的和每个项目项目下的
```
AGENTS.md
```
是「事实之源」。
区分全局与项目: 始终清晰地区分操作是在全局层面还是项目层面，并使用对应的
```
TODO.md
```
。
遵循命名规范: 创建文档时，严格遵循时间戳前缀的命名规范。

Trust
AGENTS.md
: The global and project-specific
```
AGENTS.md
```
files are the "source of truth".
Distinguish Global vs. Project: Always clearly distinguish whether operations are at the global level or project level, and use the corresponding
```
TODO.md
```
.
Follow Naming Specifications: Strictly follow the timestamp prefix naming specification when creating documents.

5.4. Emoji 使用

5.4. Emoji Usage

用户和助手约定，在文档中可使用如下的 Emoji 来标志关键信息：

🟩: 表示已完成、通过、成功。
🟥: 表示待办、有问题、未完成、需要关切。

不要随意添加其他 Emoji。

The user and assistant agree that the following Emojis can be used in documents to mark key information:

🟩: Indicates completed, passed, successful.
🟥: Indicates to-do, problematic, incomplete, requiring attention.

Do not add other Emojis arbitrarily.