# ISOS Agent Teams 软件研发模板 - 项目管理

**文档版本**: 1.0.0
**最后更新**: 2026-04-19

---

## 目录

1. [项目概况](#1-项目概况)
2. [开发里程碑](#2-开发里程碑)
3. [工作流程](#3-工作流程)
4. [协作规范](#4-协作规范)
5. [质量保证](#5-质量保证)
6. [风险管理](#6-风险管理)

---

## 1. 项目概况

### 1.1 项目简介

<!-- 填写项目简介 -->

### 1.2 技术栈

| 组件 | 技术 |
|------|------|
| 语言 | Python 3.12+ / TypeScript（前端） |
| 服务端 | FastAPI + SQLite |
| 桌面端 | PyWebView + Svelte 5 + SQLite |
| 版本控制 | Jujutsu (jj) |
| 容器化 | Docker（服务端） |

### 1.3 核心约束

| 约束 | 说明 |
|------|------|
| 模块独立性 | 各模块完全独立，禁止跨模块代码引用 |
| 通信方式 | 仅通过 REST API |
| PR 约束 | 每个 PR 只改动一个模块 |

---

## 2. 开发里程碑

### 2.1 里程碑概览

| 里程碑 | 优先级 | 核心目标 | 状态 |
|--------|--------|----------|------|
| M1: 基础架构 | P1 | <!-- 目标 --> | 待开发 |
| M2: <!-- 名称 --> | P1 | <!-- 目标 --> | 待开发 |
| M3: <!-- 名称 --> | P1 | <!-- 目标 --> | 待开发 |
| M4: <!-- 名称 --> | P2 | <!-- 目标 --> | 待开发 |

### 2.2 M1: 基础架构

**目标**: 搭建项目基础框架，确立架构模式。

**功能范围**:
- <!-- 功能1 -->
- <!-- 功能2 -->

**验收标准**:
- <!-- 标准1 -->
- <!-- 标准2 -->

---

## 3. 工作流程

### 3.1 版本控制

- 主分支：`trunk`
- 分支策略：Trunk-Based Development
- 版本控制工具：Jujutsu (jj)，并存模式
- 提交规范：使用中文类型（详见 [`team/git.md`](../team/git.md)）
- PR 约束：每个 PR 只改动一个模块，标题格式 `[模块] 描述`

### 3.2 开发流程

功能开发采用 speckit 集成流程：

```
/speckit.specify -> spec.md -> /speckit.plan -> plan.md -> /speckit.tasks -> tasks.md -> /speckit.implement
```

### 3.3 代码审查

#### 审查流程

```
代码完成 -> 自测通过 -> 创建 PR -> Agent 代码审查 -> 修改（如需） -> 合并到 trunk
```

#### 审查清单

| 审查维度 | 检查项 |
|----------|--------|
| **功能正确性** | 是否满足对应 FR 的功能要求 |
| **代码质量** | 类型注解完整、命名规范、无冗余代码 |
| **测试覆盖** | 是否达到对应模块的覆盖率要求 |
| **文档同步** | 相关文档是否已更新 |
| **模块边界** | 是否遵守模块独立性 |

### 3.4 发布流程

#### 发布前检查

| 检查项 | 命令 |
|--------|------|
| 类型检查 | `uv run mypy src/ --strict` |
| 全量测试 | `uv run pytest` |
| 代码格式 | `ruff format --check . && ruff check .` |
| 覆盖率 | 测试覆盖率满足模块要求 |

#### 版本号规则

- **MAJOR**: 所有文档共享，不轻易变更
- **MINOR**: 实质性内容/功能变更
- **PATCH**: 错别字、格式修正、Bug 修复

---

## 4. 协作规范

### 4.1 Agent Team 协作

详见 [`管理-Agent-Team分工及提示词.md`](./管理-Agent-Team分工及提示词.md)

#### Agent 角色分工

| 角色 | Skill | 职责 |
|------|-------|------|
| 需求文档 | <!-- Skill --> | <!-- 职责 --> |
| UI/UX 设计 | <!-- Skill --> | <!-- 职责 --> |
| 系统架构 | <!-- Skill --> | <!-- 职责 --> |
| 项目管理 | <!-- Skill --> | <!-- 职责 --> |
| 前端开发 | <!-- Skill --> | <!-- 职责 --> |
| 后端开发 | <!-- Skill --> | <!-- 职责 --> |
| 测试 | <!-- Skill --> | <!-- 职责 --> |
| 运维 | <!-- Skill --> | <!-- 职责 --> |

### 4.2 文档管理

- docs/ 下所有 `.md` 文件使用中文文件名
- 文档索引维护在 [`README.md`](./README.md)
- 上下文加载指引在 [`CLAUDE.md`](./CLAUDE.md)
- 文档变更需同步更新索引

### 4.3 文档一致性

文档变更后必须执行一致性检查：

| 变更类型 | 需检查的关联文档 |
|----------|-----------------|
| 功能需求变更 | `03-功能列表.md` -> `01-用户需求.md` -> `04-用户故事.md` |
| API 变更 | `09-API契约.md` -> `07-系统架构.md` -> `08-数据库设计.md` |
| 架构变更 | `07-系统架构.md` -> `11-工程规范.md` -> `08-数据库设计.md` |
| 测试变更 | `10-测试-方案.md` -> `测试-用例.md` -> `测试-计划.md` |
| 索引变更 | `README.md` -> `CLAUDE.md` |

---

## 5. 质量保证

### 5.1 测试策略

| 测试级别 | 目标 | 执行时机 |
|----------|------|----------|
| 单元测试 | 函数/类级别正确性 | 每次提交 |
| 功能测试 | 单个 FR 功能验证 | 功能完成后 |
| 集成测试 | 跨模块交互验证 | 里程碑完成后 |
| 端到端测试 | 完整用户流程 | 发布前 |
| 验收测试 | 验收标准（SC）验证 | 发布前 |

### 5.2 自动化检查

| 检查项 | 工具 | 频率 |
|--------|------|------|
| 代码格式 | `ruff format --check` | 每次提交 |
| Lint | `ruff check` | 每次提交 |
| 类型检查 | `mypy --strict` | 每次提交 |
| 单元测试 | `pytest` | 每次提交 |
| 覆盖率 | `pytest --cov` | 功能完成后 |

---

## 6. 风险管理

### 6.1 技术风险

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| <!-- 风险 --> | <!-- 影响 --> | <!-- 概率 --> | <!-- 措施 --> |

### 6.2 项目风险

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 功能范围蔓延 | 高 | 中 | 严格按 P1->P2->P3 优先级开发 |
| 模块间耦合 | 高 | 低 | 模块独立性约束；仅通过 REST API 通信 |
| 文档与代码不同步 | 中 | 中 | 文档一致性检查流程 |

---

**版本历史**:
- v1.0.0 (2026-04-19): 初始化模板