项目管家 v9

核心理念

两层能力覆盖项目全生命周期：

Skill 包结构

project-manager/                    ← Skill 根目录
├── SKILL.md                        ← 本文件（Agent 指令）

项目运行时目录结构

<项目根目录>/manager/
├── CONTEXT.md              ← L1 启动时加载的唯一文件（<80行）【项目索引：记录项目身份、当前状态、导航规则】
├── agents.md               ← 【Agent规则：记录本项目的特色Agent行为规范、自定义指令、角色设定】
├── stages/                 ← L2 阶段开发记录（按需读取）【阶段记录：按开发阶段记录开发过程】
│   ├── s1-<名称>.md
│   └── s2-<名称>.md
├── docs/                   ← L2 专项文档（按需读取）【专项文档：架构、API、规范、经验等深度文档】
│   ├── architecture.md
│   ├── api.md
│   ├── conventions.md
│   ├── troubleshooting.md
│   └── experience.md       ← 【核心经验：按模块/场景组织的可复用经验，供Agent按模块检索】
└── user-manual/            ← 项目使用手册【使用手册：面向非开发者的完整操作指南】
    ├── README.md
    ├── architecture.md
    ├── setup.md
    ├── development.md
    ├── debugging.md
    └── ui-guide.md

快速上手指南

3 步开始使用

第 1 步：初始化项目管理目录

用户说"初始化项目管理"或"创建项目管家"时，执行：

mkdir -p manager/stages manager/docs manager/user-manual

然后创建最小化的 CONTEXT.md：

# [项目名] - 上下文索引

## 项目身份
- **目标**：[一句话描述项目目标]
- **技术栈**：[主要技术选型]
- **创建时间**：[今天日期]

## 当前状态
- **阶段**：S1-初始化（进行中）
- **进度**：0%
- **正在做**：搭建项目结构
- **阻塞项**：无

## 已完成阶段摘要
（暂无）

## 导航规则
- 需要了解整体架构 → 读 docs/architecture.md
- 需要查接口定义 → 读 docs/api.md
- 需要了解 Agent 规则 → 读 agents.md
- 遇到模块问题 → 读 docs/experience.md

## 遗留问题
→ docs/experience.md#遗留问题追踪

第 2 步：创建/更新项目根目录 AGENTS.md

在项目根目录创建或更新 AGENTS.md（Trae 等 IDE 通过此文件识别项目级 Agent 约束）。

如果已存在：检查其中是否已包含「项目管理」模块。若已有则不做任何修改；若没有则在文件末尾追加「项目管理」模块，不改动文件中已有的任何内容。 如果不存在：创建新文件，写入以下完整内容：

## 项目管理

本项目使用 project-manager Skill 进行推理型项目管理。Agent 在处理本项目任何任务时，必须遵循以下规则。

### 启动行为
- **每次新对话开始**，必须先读取 `manager/CONTEXT.md`（项目索引，< 80 行）
- 读取后根据「导航规则」按需读取其他 manager/ 文件，禁止预加载全部文档
- 首次读取 CONTEXT.md 后，同时读取 `manager/agents.md`（本项目 Agent 行为规范）

### 触发 project-manager Skill 的时机
以下场景应加载/触发 project-manager Skill：
- 开始新上下文或接手项目
- 需要了解项目当前状态和进展
- 进入新的开发阶段（新功能模块、架构变更、版本迭代等里程碑）
- 完成开发后需要更新项目记录
- 用户要求生成或更新项目使用手册
- 用户提到"项目管家""更新项目记录""生成手册"

### manager/ 目录结构说明

manager/ ├── CONTEXT.md ← 项目索引（启动必读，< 80 行，回答"是什么、做到哪、详情在哪"） ├── agents.md ← Agent 行为规范（本项目特色指令和角色设定） ├── stages/ ← 阶段开发记录（按需读取，记录决策过程和经验） ├── docs/ ← 专项文档（架构、API、规范、经验等深度文档） └── user-manual/ ← 使用手册（面向非开发者的操作指南）

### 开发完成后必做
1. 更新 `manager/CONTEXT.md` 的「当前状态」（通常只改 2-3 行）
2. 在 `manager/stages/` 当前阶段文件追加本次开发的关键决策和经验
3. 有复用价值的经验同步到 `manager/docs/experience.md`
4. 检查 `manager/CONTEXT.md` 非阶段摘要区域是否超 80 行

### 自动阶段检测
当新对话开始且任务方向与 CONTEXT.md 中「正在做」显著不同时，主动判断是否需要创建新阶段文件，并询问用户确认。

### 注意事项
- `manager/` 目录下所有文件首行必须有定位说明（``）
- CONTEXT.md 是导航图，只放"是什么"和"在哪"，不放"怎么做"
- 经验文档（experience.md）只沉淀可复用的经验，偶发问题不记录

说明：根目录 AGENTS.md（大写）与 manager/agents.md（小写）是两个不同文件：

• AGENTS.md：IDE 级项目约束文件（Trae 等 IDE 自动读取），指导 Agent 如何使用 manager/ 文件和何时触发 Skill
• manager/agents.md：Skill 内部管理的 Agent 行为规范，记录项目特色的角色设定、自定义指令等 两者互补，AGENTS.md 负责"入口引导"，manager/agents.md 负责"行为细节"。

第 3 步：开始第一个开发阶段

用户说"开始新阶段"或"进入阶段2"时，执行：

1. 在 manager/stages/ 创建阶段文件 s2-<阶段名>.md
2. 更新 CONTEXT.md 的「当前状态」部分
3. 开始记录开发过程

第 4 步：生成使用手册

用户说"生成使用手册"时，执行：

1. 扫描项目结构（目录树、package.json / pom.xml / requirements.txt 等）
2. 读取 manager/docs/ 中的已有文档
3. 分析核心代码文件
4. 生成 manager/user-manual/ 下所有手册文件

自动阶段检测

Agent 不需要等用户明确说"开始新阶段"。当满足以下条件时，应主动判断是否需要创建新阶段：

触发条件（同时满足）：

1. 新对话开始（新的上下文会话）
2. 当前 CONTEXT.md 中的「正在做」与本次任务方向显著不同（涉及新模块、新需求、架构变更等）
3. 当前阶段文件中没有记录本次任务的相关内容

执行动作：

1. 在 manager/stages/ 创建新的阶段文件 s-<名称>.md
2. 更新 CONTEXT.md 的「当前状态」
3. 告知用户："检测到可能进入新阶段，已创建 s-<名称>.md，是否正确？"
4. 用户确认后继续；用户否认则合并到当前阶段

注意：

• 小修小补不算新阶段（修 bug、调样式、改配置等）
• 新阶段 = 新的可交付里程碑（新功能模块、新架构层、新版本迭代等）
• 如果不确定，先问用户

项目健康度检查

健康检查关注文档内容的合理性和有效性，不关注时间戳。Agent 应在以下时机主动执行：

• 新对话开始、接手项目时
• 用户问"项目现在什么情况"
• 自检清单中发现问题时

检查项

1. CONTEXT.md 内容合理性

• 非阶段摘要区域是否 ≤ 80 行？
• 「当前状态」是否与实际开发进度一致？
• 「导航规则」指向的文件是否都存在？
• 「阻塞项」是否仍然准确（没有已解决但未清除的阻塞）？

2. 阶段文件质量

• 是否有"孤儿阶段"（文件存在但 CONTEXT.md 没有引用）？
• 阶段文件中的决策是否记录了"为什么"而不只是"做了什么"？
• 「待更新文档」清单是否有积压超过 10 项的情况？（如有，需要集中清理）

3. 经验文档有效性

• 是否存在重复条目？（同一问题在不同模块下重复记录 → 合并）
• 是否存在"假经验"？（只记录了一次偶发问题的现象，没有可复用原则 → 删除）
• 标签体系是否一致？（同一个概念用了不同标签 → 统一）

4. 文档间一致性

• CONTEXT.md 标记为"进行中"的阶段，在 stages/ 中是否有对应文件？
• stages/ 中已完成的阶段，在 CONTEXT.md 的「已完成阶段摘要」中是否有记录？
• experience.md 中引用的阶段文件是否存在？

健康度报告格式

检查完成后，输出简要报告：

📋 项目健康度检查
- CONTEXT.md：✅ 正常 / ⚠️ [问题描述]
- 阶段文件：✅ 正常 / ⚠️ [问题描述]
- 经验文档：✅ 正常 / ⚠️ [问题描述]
- 文档一致性：✅ 正常 / ⚠️ [问题描述]
- 建议操作：[需要修复的事项列表]

适用范围与限制

✅ 适合使用的场景

❌ 不适合使用的场景

⚠️ 需要注意的边界情况

常见错误与避坑指南

❌ 错误做法 1：CONTEXT.md 超过 80 行

问题：CONTEXT.md 设计为快速加载的索引文件，超过 80 行会拖慢启动速度，违背"按需加载"原则。

正确做法：

• 只放"是什么"和"在哪"，不放"怎么做"
• 超 80 行必须精简，把详细内容移到 stages/ 或 docs/
• 用表格和链接代替长段落

示例：

# ❌ 错误：在 CONTEXT.md 里写详细设计
## 模块A设计
模块A负责用户认证，采用JWT方案，token有效期2小时，
支持刷新token，黑名单机制...（此处省略50行）

# ✅ 正确：只放索引
## 导航规则
- 需要了解模块A设计 → 读 docs/architecture.md#模块A

❌ 错误做法 2：不写定位说明

问题：新加入的团队成员不知道每个文件是干什么的，需要挨个打开看。

正确做法：所有文件首行必须写定位说明（HTML 注释格式）

示例：

# 项目名 - 上下文索引

❌ 错误做法 3：阶段文件只记结果不记过程

问题：阶段文件变成"成就列表"，丢失了决策过程、踩过的坑、为什么这么做。

正确做法：记录"为什么"比"做了什么"更重要

# ❌ 错误：只记结果
## 实现
- 完成了用户登录功能
- 完成了数据库设计

# ✅ 正确：记录决策过程
## 实现
- 用户登录功能（已完成）
  - 决策：选择 JWT 而非 Session，因为前后端分离架构
  - 踩坑：token 刷新时遇到并发问题，用 Redis 锁解决
- 数据库设计（已完成）
  - 决策：使用 PostgreSQL 而非 MySQL，因为需要 JSONB 支持

❌ 错误做法 4：agents.md 写得太笼统

问题：agents.md 里写"代码要规范"、"注意性能"，这种话等于没说。

正确做法：写具体的、可执行的规则

# ❌ 错误：笼统的规则
## 代码规范
- 代码要整洁
- 变量名要有意义
- 注意性能

# ✅ 正确：具体的规则
## 代码规范
- 函数名使用动词+名词格式（如 getUserById, calculateTotalPrice）
- 单个函数不超过 50 行，超过必须拆分
- 数据库查询必须用索引，禁止全表扫描
- API 响应时间必须 < 200ms，超过必须优化或异步

❌ 错误做法 5：使用手册只给开发者看

问题：使用手册里全是技术细节，产品/运营/客户看不懂。

正确做法：按角色分层，不同角色看不同内容

# 使用手册目录

## 快速开始（所有人）
- 3 步上手指南
- 常见问题 FAQ

## 开发者指南
- 环境搭建
- 代码规范
- API 文档

## 运维指南
- 部署流程
- 监控告警
- 故障排查

## 产品/运营指南
- 功能说明
- 操作流程
- 数据看板

❌ 错误做法 6：文档写完就不更新了

问题：代码改了，文档没更新，导致文档和代码不一致，新人被误导。

正确做法：

• 每次开发完成后，检查是否需要更新文档
• 在 stages/ 阶段文件里记录"待更新文档"清单
• 定期（如每两周）做文档审查

## 本阶段待更新文档
- [ ] docs/api.md：新增 /users/export 接口
- [ ] user-manual/setup.md：新增环境变量说明
- [ ] docs/architecture.md：更新模块C的设计

❌ 错误做法 7：experience.md 只加不删

问题：经验文档越写越长，里面混杂了大量过时经验（技术栈已换、架构已重构），Agent 检索到错误经验反而被误导。

正确做法：

• 每条经验必须有标签和创建日期，方便判断是否过时
• 新增经验前先检查是否有重复或矛盾的条目，有则合并
• 技术栈变更或架构重构时，主动清理不再适用的经验
• 只保留"当前仍然有效"的经验，过时内容删除或标记为 [已过时]

# ❌ 错误：只加不删，100+ 条经验无人清理
## [模块A]
### 场景：Vue 2 中使用 jQuery 操作 DOM
- **解决方案**：使用 $nextTick + jQuery...

# ✅ 正确：保持精简，只留有效经验
## [模块A]
### 场景：Vue 3 中处理 DOM 更新后的副作用
- **标签**：`#前端` `#生命周期`
- **创建日期**：2026-06-15
- **核心经验**：使用 onUpdated 钩子或 nextTick，不要用 setTimeout 猜测渲染完成时间

第一部分：推理型项目管理

文件定位标注规范

manager/ 目录下所有文件必须在首行写明定位说明，格式：

示例：

agents.md 文件规范

manager/agents.md 用于记录本项目特色的 Agent 行为规范，包括但不限于：

• 角色设定：本项目 Agent 的人设、说话风格
• 自定义指令：本项目特有的 Agent 行为约束
• 工具偏好：本项目优先使用哪些工具/API
• 领域知识：Agent 需要掌握的领域概念
• 交互规范：与用户交互的特殊规则

agents.md 模板

# [项目名] Agent 行为规范

## 角色设定
- **身份**：[一句话描述 Agent 在本项目中的角色]
- **风格**：[交互风格说明]

## 自定义指令
1. [本项目特有的行为约束]
2. [特殊处理规则]

## 工具偏好
- 优先使用：[工具/API列表]
- 避免使用：[不推荐的工具]

## 领域知识
- [Agent 需要掌握的领域概念1]
- [Agent 需要掌握的领域概念2]

## 交互规范
- [与用户交互的特殊规则]

CONTEXT.md 模板（硬性上限 80 行）

# [项目名] - 上下文索引

## 项目身份
- **目标**：一句话
- **技术栈**：主要技术选型（一行）
- **创建时间**：YYYY-MM-DD

## 当前状态
- **阶段**：阶段N-<名称>（进行中/已完成）
- **进度**：X%
- **正在做**：当前聚焦的2-3件事
- **阻塞项**：当前卡住的问题（没有则写"无"）

## 已完成阶段摘要
| 阶段 | 做了什么 | 详情 |
|------|----------|------|
| S1   | 一句话概括 | → stages/s1-xxx.md |
| S2   | 一句话概括 | → stages/s2-xxx.md |

## 导航规则
- 修改[某模块]相关代码 → 读 stages/sN-xxx.md
- 遇到[某模块/功能]问题 → 读 docs/experience.md#模块名
- 需要了解整体架构 → 读 docs/architecture.md
- 需要查接口定义 → 读 docs/api.md
- 需要了解Agent行为规范 → 读 agents.md

## 遗留问题
→ docs/experience.md#遗留问题追踪

写 CONTEXT.md 的铁律：只放"是什么"和"在哪"，不放"怎么做"。超 80 行必须精简。

stages/ 阶段文件模板

# 阶段 N：<阶段名称>

## 目标
本阶段要达成什么
- [ ] 验收标准是否明确？

## 需求
- 需求1
- 需求2
- [ ] 需求来源（用户反馈 / 内部规划 / 技术债务）：
- [ ] 不做的边界是什么？

## 设计
关键设计决策
- [ ] 是否有现成方案可复用？
- [ ] 影响范围评估（哪些模块会受影响）：

## 实现
- 任务1：状态（已完成/进行中）
  - 决策：为什么这么做
    - [ ] 候选方案有哪些？为什么排除其他？
  - 经验沉淀：
    - [ ] 是否遇到意外情况？根因是什么？
    - [ ] 解决方案的核心逻辑？
    - [ ] 能否提炼为可复用原则？
    - [ ] 是否需要同步到 experience.md？
- 任务2：状态

## 复盘
- [ ] 进度偏差及原因：
- [ ] 是否有可复用的方法论：
- [ ] 下一阶段需规避什么：

## 待更新文档
- [ ] docs/api.md：[需要更新的内容]
- [ ] user-manual/setup.md：[需要更新的内容]

docs/ 专项文档模板

architecture.md

# 架构说明

## 系统架构图

[模块A] → [模块B] → [模块C]

## 核心模块表
| 模块 | 职责 | 关键文件 |
|------|------|----------|
|      |      |          |

## 技术选型表
| 技术 | 选型理由 |
|------|----------|
|      |          |

api.md

# 接口定义

## 认证方式

## API 列表
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
|      |      |      |      |

conventions.md

# 项目约定

## 代码规范

## 命名约定

## 提交规范

troubleshooting.md

# 问题排查

## 常见问题表
| 问题 | 原因 | 解决 |
|------|------|------|
|      |      |      |

experience.md

# 项目核心经验

## [模块A / 功能A]

### 场景：[一句话描述什么情况下会触发]
- **标签**：`#性能` / `#安全` / `#兼容性` / `#架构` / `#调试` 等
- **创建日期**：YYYY-MM-DD
- **现象**：
- **根因分析**：
- **解决方案**：
- **核心经验**：[提炼为一句话可复用原则]
- **关联阶段**：→ stages/sN-xxx.md

### 场景：[...]

## [模块B / 功能B]

### 场景：[...]

## 遗留问题追踪

| 问题描述 | 优先级 | 预计解决阶段 | 关联模块 | 详情 |
|----------|--------|--------------|----------|------|
|          | P0/P1/P2 |              |          | → stages/sN-xxx.md |

Agent 工作流（推理模式）

新上下文启动

1. 读 CONTEXT.md（< 80 行）
2. 读 agents.md（项目特色 Agent 规则）
3. 若项目根目录存在 AGENTS.md，读取其中的「项目管理」模块了解项目背景与强制约束
4. 不读其他文件——除非当前任务明确需要
5. 基于全局认知开始工作

接到具体任务

1. 对照 CONTEXT.md 的「导航规则」判断需要读哪个文件
2. 对照 agents.md 的「上下文补充规则」和「决策偏好」调整行为
3. 只读相关的文件

完成开发后

1. 在 stages/ 当前阶段文件追加开发点
2. 更新 CONTEXT.md 的「当前状态」（通常只改 2-3 行）
3. 有长期价值的知识写入 docs/
4. 若发现新的 Agent 行为规则，更新 agents.md
5. 检查 stages/ 中的「经验沉淀」，将有复用价值的经验同步到 docs/experience.md
6. 检查是否需要更新文档，记录到 stages/ 的「待更新文档」清单
7. 执行自检清单（见下方），确认文档状态正确
8. 检查 CONTEXT.md 非阶段摘要区域行数：除「已完成阶段摘要」表格外，其余内容合计不得超过 80 行；超出时将详细内容迁移到 stages/ 或 docs/

自检清单（每次开发完成后必执行）

完成开发后，逐项确认：

• CONTEXT.md「当前状态」是否反映了最新进度？
• stages/ 当前阶段文件是否记录了本次开发的关键决策和经验？
• 导航规则是否仍然有效（指向的文件是否存在）？
• 新增的经验是否已同步到 experience.md（如有复用价值）？
• 本次开发是否产生了需要新建文档的需求？
• experience.md 中是否有与本次经验重复的条目？（如有，合并而非新增）
• CONTEXT.md 非阶段摘要区域是否仍在 80 行以内？

第二部分：项目使用手册

设计理念

项目使用手册面向所有使用者，不仅是开发者。包括新加入的团队成员、运维人员、甚至非技术的利益相关者。

手册结构

README.md（手册目录与快速开始）

# [项目名] - 使用手册

## 快速开始
1. 安装 → 2. 配置 → 3. 运行

## 手册目录
- 架构说明 → architecture.md
- 环境搭建 → setup.md
- 开发指南 → development.md
- 调试手册 → debugging.md
- UI 操作指南 → ui-guide.md

architecture.md（架构说明）

• 系统架构图（模块划分和数据流）
• 核心模块表（职责 + 关键文件）
• 技术选型表（选型理由）

setup.md（环境搭建与部署）

• 前置要求（运行时、依赖、环境变量）
• 本地开发环境搭建步骤
• 生产部署方式（Docker / 直接 / 云服务）
• 常见安装问题

development.md（开发指南）

• 代码规范（命名、目录、提交）
• 功能开发流程（分支 → 开发 → PR → 审查 → 合并）
• 测试运行方式
• 项目约定

debugging.md（调试手册）

• 日志系统（位置、级别、实时查看）
• 常见问题排查表（问题 → 原因 → 解决）
• 性能分析方法
• 已知问题

ui-guide.md（UI 操作指南）

• 界面总览
• 页面功能说明
• 交互规范

Agent 手册生成工作流

首次生成

1. 用户说"生成项目使用手册"
2. Agent 扫描项目结构（目录树、package.json / pom.xml / requirements.txt 等）
3. 读取 manager/docs/ 中的已有文档
4. 分析核心代码文件（入口文件、路由配置、主要模块）
5. 生成 manager/user-manual/ 下所有手册文件
6. 报告生成结果

增量更新

1. 用户说"更新使用手册"
2. Agent 对比当前项目结构和已有手册的差异
3. 只更新有变化的部分

异常处理与边缘情况

情况 1：CONTEXT.md 超 80 行

检测：每次更新 CONTEXT.md 后，检查行数

处理：

wc -l manager/CONTEXT.md

如果超过 80 行：

1. 把"怎么做"的内容移到 stages/ 或 docs/
2. 只保留"是什么"和"在哪"
3. 用表格和链接代替长段落

情况 2：阶段文件冲突（多人开发）

检测：git pull 时发现 stages/ 文件冲突

处理：

1. 按模块拆分阶段文件（如 s2-frontend.md、s2-backend.md）
2. 或者按时间拆分（如 s2-week1.md、s2-week2.md）
3. 在 CONTEXT.md 的导航规则中说明拆分逻辑

情况 3：项目暂停后重启

检测：用户说"继续上次的项目"，但 CONTEXT.md 的状态已过时

处理：

1. 先问用户："上次做到哪了？有什么变化？"
2. 更新 CONTEXT.md 的「当前状态」
3. 如果有新的需求或设计变更，先更新 stages/ 文件
4. 再开始新工作

情况 4：技术栈频繁变更

检测：CONTEXT.md 的「技术栈」字段经常需要修改

处理：

## 项目身份
- **当前技术栈**：[当前使用的技术]
- **历史技术栈**：
  - 2024-01 ~ 2024-06：Vue 2 + Element UI
  - 2024-07 ~ 至今：Vue 3 + Element Plus

情况 5：文档和代码不一致

检测：用户反馈"文档里的接口和代码对不上"

处理：

1. 立即修复文档
2. 在 stages/ 记录"文档滞后"的原因
3. 建立"文档审查"机制：每次 PR 必须检查文档是否需要更新
4. 在 troubleshooting.md 记录这次问题，避免再犯

核心原则

1. 按需加载，不预加载：启动只读 CONTEXT.md，其余按需查阅
2. CONTEXT.md 是导航图：回答"是什么、做到哪、详情在哪"，不回答"怎么做"
3. 80 行铁律：CONTEXT.md 严格控制在 80 行以内
4. 文件首行标注定位：manager/ 下所有文件首行写明用途说明
5. 手册面向所有人：不仅是开发者，产品/测试/运维都能从中获取所需信息
6. 渐进式建设：所有文件按需创建，不强制初始化全部内容
7. 跨平台兼容：Trae 放 .trae/skills/project-manager/
8. Agent 规则显性化：项目特色行为写入 agents.md，不依赖隐式假设
9. 记录"为什么"比"做了什么"更重要：决策过程和踩坑经历是核心资产
10. 文档和代码同步更新：每次开发完成后检查文档是否需要更新
11. AGENTS.md 主动创建：初始化时必须创建项目根目录的 AGENTS.md，指导 IDE Agent 如何使用 manager/ 文件和触发 Skill；后续开发中保持与项目状态同步
12. 经验沉淀原则：阶段记录中的问题解决后，只将"有复用价值"的经验同步到 experience.md，偶发问题不沉淀
13. 自动阶段检测：新对话 + 显著变更 = 可能进入新阶段，主动提示并创建阶段文件
14. 内容健康优先：健康检查关注文档内容的合理性、一致性和完整性，不关注时间戳
15. 完成必自检：每次开发完成后必须执行自检清单，确认文档状态正确后再结束

本内容由 Coze AI 生成，请遵循相关法律法规及《人工智能生成合成内容标识办法》使用与传播。