# AI通用项目管理Skill

**Repository Path**: formalization/GeneralReqManage

## Basic Information

- **Project Name**: AI通用项目管理Skill
- **Description**: 一套可回归、有长期索引记忆、无学习成本的AI项目需求管理与协作体系
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-01
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通用需求管理体系
一套**可回归、有长期索引记忆、无学习成本** 的AI项目需求管理与协作体系:任何项目(存量接入或新建)复制一组文件即可拥有完整能力;任何能读写文件的 agent 读完契约文档即可接管。

## 设计目标

| 目标 | 实现手段 |
|---|---|
| 精准定位,不重读项目 | 两层结构:轻量索引 `index.json`(每需求一行,含直达文件名)→ 按需读单个详情文件 |
| 省 token | 日常操作只加载索引;协作规则约束读取/输出习惯(禁止扫描项目、禁止批量读详情) |
| agent 容易接入、换了也能用 | 规则收敛在纯文档(`AGENT.md` / `rules/`);根下多入口(`CLAUDE.md`/`AGENTS.md`)只做导航,新工具加一个入口文件即接入 |
| 可移植 | 固定目录 `requirements/` + `rules/`,复制即接入 |

## 目录结构

```
requirements/
├── AGENT.md        # ★ 需求契约:读取协议 / 写入协议 / 状态机 / 工作流规则(任何 agent 必读)
├── index.json      # ★ 索引:每需求一行(id/标题/状态/优先级/模块/文件名/概要;子需求含 parent 指向父需求)
├── _schema.json    # 字段定义与状态机,schemaVersion 版本化
├── _template.md    # 新需求模板
├── _doubt-log.md   # 存疑记录簿模板(req init 实例化为常设 REQ-0000)
├── REQ-XXXX-*.md   # 需求详情:frontmatter 结构化字段 + 正文(背景/验收标准/方案/实现记录)
├── REQ-XXXX-*/     # 需求文件夹(可选):同类需求项+子需求合并打包,父需求详情兼作文件夹索引
└── _archive/       # 归档区(可选):失去保留价值的需求移入,可逆恢复
rules/
└── ai-collaboration.md  # ★ AI 协作公共规则(语言无关):读取/输出/编辑/任务组织/红线/文档维护
.claude/skills/req/      # /req skill:自包含(templates/ 内嵌全套模板),负责 init/upgrade/日常操作
  └── templates/         #   由 package_skill.py 从真源同步生成,勿手改
CLAUDE.md / AGENTS.md    # agent 自动加载入口:只做导航,指向上面各真源
package_skill.py         # 真源 → skill 模板同步 + 打包外发 zip
dist/req-skill-v*.zip    # 可外发的 skill 安装包(package_skill.py 生成)
```

## 接入一个新项目

**方式一:已装 /req skill(推荐)** —— 在目标项目里执行 `req init <项目名>`,自动完成:拷贝契约/规则/模板、生成空索引并实例化存疑记录簿 REQ-0000、幂等登记 CLAUDE.md / AGENTS.md 入口导航。

存量项目(已有代码/文档)接入后,再执行一次 `req import` 反向解析:agent 勘察项目代码与文档,归纳出**中文命名的需求树**(需求项/需求子项,子项通过 `parent` 字段挂在父需求下),已实现标 `done`、未实现标 `backlog`,导入即得存量全景。幂等保护:已有需求数据时拒绝执行,不会覆盖既有管理事实。

项目持续演进后,可随时执行 `req import 重解析` **对账**:以代码为事实源重新勘察、与既有需求逐条比对——描述优化、title 中文化、状态滞后推进、缺口功能补录等无冲突变更自动落盘并逐条汇报;疑似已移除、范围重叠、层级调整等冲突只列清单交用户裁决。

**方式二:手动(无 Claude Code / 无 skill 时)**

1. **复制**:
   - 必拷:`requirements/`(AGENT.md、_schema.json、_template.md、_doubt-log.md,示例 REQ 文件不拷;`index.json` 拷后清空 `requirements` 数组、`project` 改为目标项目名,并从 `_doubt-log.md` 实例化 REQ-0000 存疑簿)+ `rules/ai-collaboration.md`
2. **建入口**:目标项目根下放导航入口——`CLAUDE.md`(Claude Code/Cline)与/或 `AGENTS.md`(Codex 等),只放导航表,不复制规则本身(模板见 skill 的 `templates/entry-snippet.md`)。

手动接入的存量项目同样可让 agent 按 `AGENT.md` 的「首次导入」协议反向解析,生成需求树。

建议把 `requirements/` 与 `rules/` 纳入 git,需求与规则变更同库可追溯。

## 安装 / 外发 / 升级

`python package_skill.py` 生成分发 zip(`dist/req-skill-v<ver>.zip`,含 install.bat / install.sh / skill 全套):

| 部署方式 | 做法 | 适用 |
|---|---|---|
| **项目内部署(推荐)** | 解压 zip,把 `req/` 复制到项目 `.claude/skills/req/`,项目内执行 `req init` | 体系随项目走、随 git 提交,可在项目内自我完善 |
| 全局部署 | 运行 install 脚本装到 `~/.claude/skills/req/`,任意项目 `req init` | 多项目快速起步,基线统一 |

- **外发**:发送 zip 即可;体系本体 agent 无关,不用 Claude Code 的接收方按「手动方式」接入(`req/templates/` 就是全套模板)。
- **基线升级**:模板源改进后重新打包分发 → 已接入项目执行 `req upgrade`(**合并**语义:同步未定制文件,定制过的逐条合并、冲突由用户决定,绝不碰数据与入口)。

## 体系自我完善(自治演化)

外发的体系不保证完美,**项目内的体系文件才是真源**,用着不对就当场修:

```
使用中发现规则问题(agent 发现 或 用户提出)
→ 当场修订项目内体系文件(AGENT.md / _schema.json / rules/*)
→ 在该文件尾部「演进记录」追加一行(改了什么 + 为什么)
→ schema 变更递增 schemaVersion,向后兼容
→ 一句话汇报;req diff 随时可查看本项目相对出厂基线的全部演化
```

- 数据(`index.json`、`REQ-*.md`)与规则修订互不干扰,各走各的协议。
- 进化成熟后反哺模板源:`req diff` 的差异 + 演进记录带回模板源人工评审合入,再分发——不自动同步,避免未经评审的规则漂移扩散。

## 接入一个新 agent(零成本)

- agent 工具会在项目根自动加载自己的入口文件(`CLAUDE.md`、`AGENTS.md`、…);入口只做导航,指向规则真源。
- 出现新工具时:照抄一个现有入口文件、改个文件名即可,规则零复制、零漂移。
- 换 agent、升级 agent,契约不变,管理不断。

## 日常工作流

```
提需求(自然语言)→ agent 按 _template.md 建文件 + 更新 index.json
实现功能          → agent 先在索引确认需求存在,写码(遵守 rules/ 协作规则);小任务直做不建项(判据见 AGENT.md 工作流规则)
完成验证          → agent 逐 AC 执行验证方式核验(✅/👤/❌),同步完成度;全 ✅ 自动验收进 done,含人工项停 review 等用户
查进度            → agent 只读 index.json 即可汇报,零详情加载
看需求树          → req tree 按 parent 分组渲染(需求项 → 子项),节点带完成度,看树即知进展
```

状态机:`backlog → doing → review → done`,旁路 `blocked / rejected`。

## 与 AiEngineer 插件的衔接

插件零 AI:按 `_schema.json` 解析 frontmatter 与索引,渲染树形视图、做手动微调(v3 起索引与 frontmatter 含可选 `parent` 字段,树形视图直接由它分组派生);所有"自然语言 → 结构化数据"的工作(含 `req import` 反向解析)交给 agent。体系升级只动 `requirements/` 下的模板与契约,插件按 schemaVersion 兼容。

## 规则演进记录

- 2026-10-31: skill 范围收敛为纯需求管理:移除 C++/Qt 编码规范选装模板,rules/ 仅保留语言无关的 AI 协作规则,init 不再按技术栈加拷编码规范。
- 2026-10-27: 「小任务直做不建项」补归口父项生命周期(下游项目反哺合入):小改动在对应需求实现记录登记即可,不建子需求、不进索引。
- 2026-10-22: 需求归档与瘦身三档整理(直接删除→归档→建议清单);REQ-0000 存疑记录簿常设必备;需求文件夹形态与分层按需加载(2026-10-14)。
- 2026-08-27: v3 需求树(可选 `parent` 字段,需求项/子项)与首次反向解析 `req import` / `req tree`,存量项目接入即得中文需求全景(REQ-0007)。
- 2026-08-27: 体系创建(REQ-0001);整合既有项目通用规则为 `rules/ai-collaboration.md`,引入多 agent 入口模式(REQ-0002)。