# agent-delivery-framework

**Repository Path**: clawme/agent-delivery-framework

## Basic Information

- **Project Name**: agent-delivery-framework
- **Description**: Agent 驱动交付项目管理框架 - 种子仓库，clone 后重命名为项目名即可使用
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-05-13
- **Last Updated**: 2026-05-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---

title: "Agent 驱动交付项目管理框架"
type: project
status: seed
version: "2.0"
created: "2026-05-13"
updated: "2026-05-14"
---

# Agent 驱动交付项目管理框架

> 一个简洁的交付项目管理框架，Agent 驱动，文档即代码。

---

## 这是什么

这个框架帮助交付项目团队用 Agent 驱动的方式管理项目文档。

核心特点：

- **clone 即用**：种子仓库，clone 时指定项目名即可直接使用
- **Agent 驱动**：Agent 根据规则和 Skill 自动完成文档工作
- **文档即代码**：Markdown + Git，版本可追溯
- **过程即时记录**：工作日志、交付物、过程文档都在产生时创建

## 适配工具

1. 首推TRAE
2. 其他支持skill、command、rule规则的开发工具
3. 如果使用其他工具，需要支持自动加载claude.md到当前上下文

## 快速开始

### 1. 创建新项目

clone 时直接指定项目名称作为文件夹名，一步到位（文件夹名即为仓库根目录，不会多嵌套一层）：

```bash
git clone https://gitee.com/clawme/agent-delivery-framework.git 我的项目
cd 我的项目
git remote set-url origin <你的新项目仓库地址>
```

### 2. 初始化项目

告诉 Agent：「初始化项目」。Agent 会先检查 **`工作日志/` 目录是否存在**（与 `CLAUDE.md` 状态判断一致）；不存在则按 `.trae/INIT_GUIDE.md` 引导创建目录与项目文件。Skill / Command 分层与触发规则见**本文件下文「Skill 与 Command 架构说明」**。

Agent 会：

1. 生成 README.md 和 KNOWLEDGE.md
2. 填充项目基本信息
3. git commit + push

### 3. 开始工作

| 你想做什么  | 对 Agent 说     |
| ------ | ------------- |
| 写文档    | "帮我写一份需求分析文档" |
| 生成周报   | "生成周报"        |
| 生成进度报告 | "生成进度报告"      |
| 任务完成   | "这个任务完成了"     |

## 目录结构

```
.
├── CLAUDE.md              ← 项目上下文（Agent 读取）
├── README.md              ← 项目状态（本文件）
├── KNOWLEDGE.md           ← 项目知识沉淀
├── .trae/                 ← Agent 约束体系
│   ├── rules/             ← 行为红线
│   ├── commands/          ← 工作流（可修改）
│   ├── skills/            ← 单元化 Skill
│   ├── skill-architecture.md ← 架构入口 stub（正文在 README 同名节）
│   └── INIT_GUIDE.md      ← 初始化引导流程
├── 工作日志/              ← 每日工作记录
├── 交付物/                ← 最终成品
├── 过程文档/              ← 草稿、历史版本、输入材料
└── 里程碑/                ← 里程碑评审纪要
```

## 文档结构

本仓库刻意把「给人看的全景说明」与「工具自动加载的入口」拆开，避免单文件承担所有职责或产生重复维护：

| 文件 | 角色 | 为何不全部并入 README |
|------|------|------------------------|
| **`CLAUDE.md`** | TRAE 等环境**自动注入**的项目上下文（YAML 占位符、读取优先级、意图路由） | 合并正文会削弱自动加载的「薄上下文」；保留本文件为权威入口，README 承担展开说明 |
| **`.trae/INIT_GUIDE.md`** | **仅未初始化**（无 `工作日志/`）时由 Agent 执行的步骤清单 | 初始化完成后很少再读；全文塞进 README 会长期占用篇幅 |
| **`README.md`**（本文件） | 人类与 Agent 共读的**项目状态、概念与架构全文** | 适合放 Skill/Command 分层、PDCA、触发规则等「常查阅」说明 |
| **`.trae/rules/*.md`** | 可机读的**强制约束**（`alwaysApply` 等） | 需独立文件供工具按约定加载，不宜只活在 README |
| **`.trae/commands/*.md`**、**`.trae/skills/*/SKILL.md`** | **可执行编排 / 原子步骤**（输入输出、调用顺序） | 与说明性架构文档分层，避免「一篇 README 既是规范又是执行脚本」 |

## 核心概念

### Skill

单元化操作，每个 Skill 只做一件事：

- `doc-plan`：生成文档大纲
- `doc-write`：按大纲撰写
- `doc-review`：审查质量
- `doc-import`：批量导入文档
- `weekly-report`：生成周报
- `progress-report`：生成进度报告
- `wbs-create`：生成 WBS 文档
- `task-closure`：任务收尾
- `knowledge-update`：更新知识

### Command

工作流编排，定义 Skill 的调用顺序。项目经理可以修改：

- `doc-pipeline`：文档生成流水线（plan → write → review → deliver）

完整分层、PDCA 与触发规则见**下文「Skill 与 Command 架构说明」**。

### Rule

行为红线，Agent 必须遵守：

1. 路径安全
2. 文件创建最小化
3. 提交规范

## Skill 与 Command 架构说明

> 本节定义本框架（Agent 驱动交付文档 + 本地 Git 知识库）的分层职责、技能分类、PDCA 闭环归属与触发规则，用于抑制 **Skill 膨胀**：新增能力前先判断应落在 Command 编排、既有 Skill 的扩展，还是 KNOWLEDGE / PingCode 分工边界。

### 1. 第一性原则：每层解决什么问题

| 层次 | 载体 | 解决的问题 | 反模式（Skill 膨胀） |
|------|------|------------|----------------------|
| **项目锚点** | `CLAUDE.md` | 项目是谁、读什么、先判断初始化与否、意图路由到 Command/Skill | 把项目背景写进多个 Skill |
| **行为红线** | `.trae/rules/*.md` | 安全、日志、提交、敏感信息与 PingCode 分工等**不可协商**约束 | 在 Skill 里重复「别忘了写工作日志」 |
| **元数据** | `.trae/rules/metadata-standard.md` | 交付物/日志/周报等文档可被工具与人类一致消费 | 每种文档各造一套 YAML |
| **编排（Orchestrator）** | `.trae/commands/*.md` | **跨多步、有顺序、有退出条件**的端到端工作流（谁在读谁、几轮检查、交付落盘） | 为「plan→write→review」再拆 3 个微型 Command |
| **原子 Skill** | `.trae/skills/*/SKILL.md` | **单职责、可组合**的可重复动作（一次调用做好一类事） | 为每个文档类型各做一个 Skill |
| **运行时判断** | Agent | 缺信息时提问、异常降级、未在表内的合理动作 | 为「问用户」单独做一个 Skill |

**结论**：重复出现且**输入输出稳定** → Skill；**多 Skill 固定串联与闭环** → Command；**一次性上下文** → CLAUDE / 对话；**任务/风险状态** → PingCode；**可复用组织经验** → `KNOWLEDGE.md`（经 `knowledge-update` 或 task-closure 中的可选步骤写入）。

### 2. 技能分类：Orchestrator、P/D/C/A、Gate

- **Orchestrator（Command）**：定义阶段顺序、人机在环（如大纲确认）、轮次上限与交付落点；对所属工作流承担 **PDCA 主闭环**（见第 3 节）。
- **P（Plan）**：把目标变成可执行结构（大纲、分解、记录「将要做什么」）。
- **D（Do）**：生成主体产物（正文、导入、周报/进度报告文稿、会议纪要文稿等）。
- **C（Check）**：质量与完整性闸门，可阻塞回流到 D。
- **Gate（闸门 Skill）**：以 **通过/不通过** 为主产出，触发返工；本仓库中 **`doc-review` 为显式 Gate**；`task-closure` 含「收尾检查」的**轻量 Gate**（Git/状态/日志是否到位）。
- **A（Act / 改进与闭环）**：把检查结果沉淀为知识、习惯或下一周期输入（更新 KNOWLEDGE、复盘、任务收尾）。

### 3. 全量映射表：12 个 Skill + `doc-pipeline` Command

| 名称 | 类型 | PDCA 阶段 | 闭环归属（谁负责「收口」） |
|------|------|-----------|---------------------------|
| **doc-pipeline**（Command） | Orchestrator | P→D→C→（部分 A） | **Command 自身**：交付目录、索引、工作日志、提交；可选 A 见下文 |
| doc-plan | 原子 Skill | P | 由 **doc-pipeline** 或显式多步编排收口；单独调用时由 **Agent + 用户确认** 收口 |
| doc-write | 原子 Skill | D | 由编排 Command 或用户指定落盘步骤收口 |
| doc-review | Gate / C | C | **不单独闭合业务闭环**：返回审查结论；**doc-pipeline** 或人工决定返工/放行 |
| doc-import | 原子 Skill | D（批量落地） | **doc-import** 执行导入报告与落盘；上游若属项目流程则由触发该流程的 Command/用户收口 |
| weekly-report | 原子 Skill | D（周期性状态稿） | **调用方**：固定周报节奏可由用户约定 + **task-closure** 合并提交；与 PingCode 状态同步由人在 PingCode 完成 |
| progress-report | 原子 Skill | D（深度/阶段性稿） | **调用方**：里程碑或纠偏场景由用户/PM 收口并归档 |
| wbs-create | 原子 Skill | P | **调用方**：WBS 定稿后通常进 **PingCode** 建工作项；文档侧由工作日志或 task-closure 记录 |
| task-closure | A + 轻量 Gate | A（收尾） | **task-closure 自身**：日志、README、提交；可选触发 **knowledge-update** |
| knowledge-update | A | A | **knowledge-update** 或包含其的 **task-closure** 收口到 `KNOWLEDGE.md` |
| meeting-minutes | 原子 Skill | D（会议信息结构化） | **调用方**：归档至 `过程文档/` 或 `交付物/` 并写工作日志；行动项入 PingCode |
| decision-record | 原子 Skill | D + A 边界 | **调用方**：决策落 `过程文档/`/`交付物/`；若形成组织经验则再走 **knowledge-update** |
| retrospective | A | A | **retrospective** 产出复盘文档；改进项入 PingCode 或下一周期计划 |

### 4. PDCA 规则

1. **完整 PDCA 默认由 Command 拥有**  
   例：`doc-pipeline` 覆盖 读上下文 → plan → write → review（可循环）→ 交付与日志，形成该文档主题的闭环。

2. **Gate Skill 不宣称「项目闭环已完成」**  
   `doc-review` 只输出检查结论；**放行后的交付与记录**仍由 Command 或 `task-closure` 完成。

3. **「Gate + 改进」组合闭合 A**  
   审查未通过 → 返工（D）；通过后 → 可选 **knowledge-update**（可复用教训）或 **retrospective**（周期性改进），避免把 A 写进每一个 C。

4. **原子 Skill 声明约定**（建议在各自 SKILL 中保持简短一行）  
   - **phase**：`P` \| `D` \| `C` \| `A` \| `Gate`  
   - **who_closes_loop**：`command:doc-pipeline` \| `skill:task-closure` \| `skill:knowledge-update` \| `user` \| `agent`  

5. **无 Command 的单次调用**  
   闭环由 **Agent 显式步骤** + **用户** 承担（例如仅调用 `weekly-report` 而不收尾提交）。

### 5. 触发器与选用指南

| 意图 | 使用 | 说明 |
|------|------|------|
| 按**周**向干系人同步整体状态、风险与下周计划 | **weekly-report** | 节奏固定、读者偏「管理层/客户例行」 |
| **里程碑**、**阶段汇报**、**异常/纠偏**或需与基线对比 | **progress-report** | 粒度更深，可绑定具体阶段或问题 |
| 可复用的踩坑、决策、接口约定、跨项目可迁移经验 | **knowledge-update**（**建议必须**） | 写入 `KNOWLEDGE.md`；与 PingCode 任务状态无关 |
| 一次性措辞、单次客户沟通记录 | **knowledge-update**（**可选**） | 避免 KNOWLEDGE 噪声；可只放 `过程文档/` |
| 任务完成、分支收尾、准备切换上下文 | **task-closure** | 对齐 core-rules 工作日志与提交 |
| 从需求到交付的正式文档 | **doc-pipeline**（Command） | 结束于 `交付物/`、索引与工作日志；**文末可选**见 `doc-pipeline.md` 与第 6 节 |

**与 doc-pipeline / task-closure 的衔接**：文档交付闭环以 **doc-pipeline** 为准；跨任务/里程碑的 Git 与状态收口以 **task-closure** 为准；二者都可触发**可选的** `knowledge-update`，但不应每次写文档都膨胀 KNOWLEDGE。

### 6. TRAE 与加载说明

在 TRAE 中，`.trae/skills/`、`.trae/commands/`、`.trae/rules/` 由工具按约定加载；**无需**在 INIT_GUIDE 所述历史步骤意义下「手动注册」Skill/Command 到 TRAE。初始化重点是 **目录、`README.md`/`KNOWLEDGE.md`、工作日志约定** 等项目文件，而非向 IDE 再登记一遍技能表。

### 7. 项目经理视角评审

从真实 PM 工作流审视本框架（clone/init、每日工作日志、文档交付、周报、里程碑、风险/任务交给 PingCode、知识沉淀、任务交接）：

| 工作流 | 现状优点 | 差距 / 摩擦 |
|--------|----------|----------------|
| **clone / init** | `工作日志/` 存在与否判断清晰 | INIT 文案仍易让人以为要「注册」Skill；种子无 `工作日志/` 时 core-rules「必须写日志」与未初始化状态并存，Agent 需优先 INIT |
| **每日工作日志** | core-rules 强制 | 未初始化无目录时不能机械执行，需先 INIT 或明确用户不要求种子初始化 |
| **文档交付** | doc-pipeline 清晰 | 与 KNOWLEDGE 更新关系过去未写明，易每次文档都改 KNOWLEDGE |
| **周报 vs 进度** | 两 Skill 分离 | 选用规则依赖口头传递，本文已表格式固定 |
| **里程碑** | `里程碑/` + progress-report | PingCode 里程碑状态与本地纪要无自动同步，需人工 |
| **风险交 PingCode** | core-rules 已提示登记 | 各 Skill 未统一插入「请在 PingCode 中登记」提示语，依赖 Agent 记忆 |
| **知识捕获** | KNOWLEDGE + knowledge-update | 「必须/可选」边界 formerly 模糊 |
| **任务交接** | task-closure | 与 doc-pipeline 结束动作部分重叠（日志、提交），需约定「文档闭环用 pipeline，任务切换用 closure」 |

### 8. 根据评审的修订说明

以下修订已在本轮同步到仓库（概念 + 部分文件）：

1. **CLAUDE.md**：补充「初始化类意图仍先检查目录」、`KNOWLEDGE.md` 缺失时的读取策略、指向架构说明（正文见本 README 本节），降低未初始化时的误读。  
2. **README.md**：收纳架构全文；初始化表述与 CLAUDE 对齐（以 `工作日志/` 为准）；本节为 Skill/Command 分层与触发的**唯一权威正文**。  
3. **doc-pipeline.md**：在交付段增加「仅当有可复用教训时才可选调用 knowledge-update」，避免 KNOWLEDGE 膨胀。  
4. **`.trae/skill-architecture.md`**：保留为**重定向 stub**，避免旧链接失效；请勿在 stub 内重复维护表格。  
5. **代表性 Skill**：在 `doc-plan`、`task-closure` 增加极简 **phase / who_closes_loop** 声明，其余 Skill 以本节为权威，避免 12 份重复维护。

> **维护说明**：调整 Command 编排或增减 Skill 时，同步更新上表与第 5 节触发器。

## 设计哲学

### 第一性原则

- Agent 需要什么信息？→ 写在 CLAUDE.md 里
- Agent 必须做什么？→ 写在 rules 里
- 反复出现的操作？→ 封装为 Skill
- 其他一切？→ 交给 Agent 自己判断

### 工程控制论

只有一个闭环：**工作 → 记录 → 反思 → 改进**

### 与 PingCode 的分工

| 维度       | PingCode | 本框架    |
| -------- | -------- | ------ |
| 需求/任务/风险 | 录入、跟踪    | 生成分析文档 |
| 里程碑      | 设定、更新    | 评审纪要   |
| 周报/进度报告  | —        | 生成文档   |
| WBS      | 工作项管理    | WBS 文档 |

## Git 规范

### Commit Message 前缀

| 前缀       | 场景    | 示例                     |
| -------- | ----- | ---------------------- |
| `feat:`  | 新增交付物 | `feat: 需求分析文档 V1.0`    |
| `log:`   | 工作日志  | `log: 2026-05-13 工作日志` |
| `fix:`   | 修正/变更 | `fix: 修正数据错误`          |
| `docs:`  | 文档更新  | `docs: 更新 README 状态`   |
| `chore:` | 杂项维护  | `chore: 项目归档`          |

---

> 最后更新：2026-05-14 | Agent 驱动交付项目管理框架 v2.0