# ErrLens 宪法 + 目录框架 整改报告

> 审核日期：2026-05-23  
> 审核范围：AGENTS.md、AI 配置文件、目录结构、提示词库、工作流  
> 审核标准：三文件一致性、路径覆盖率、语义完备性、工作流闭环

---

## 修改总览

| # | 硬伤 | 动作 | 修改文件数 |
|---|------|------|----------|
| 1 | 三文件对 Dev AI 操作 task.md 权限矛盾 | 统一语义，引入 R/W/RW 体系 | 3 |
| 2 | coder.json 漏掉 AGENTS.md 中的职责 | 补全职责列表 | 1 |
| 3 | `projects/*/src/` 不覆盖后端代码 | server/config/types 移入 src/ | 4 |
| 4 | `.ai/prompts/` 完全空白 | 创建 3 份提示词 + 2 份索引 | 5 |
| 5 | JSON 配置无语义定义 | 加 description + 优先级规则 | 3 |
| 6 | Workflow 缺少循环分支 | 8 阶段→4 阶段 + retry 配置 | 2 |

---

## 详细变更

### 硬伤 1+2+5：权限体系统一

**发现问题**：`AGENTS.md`、`coder.json`、`tester.json` 对同一路径的权限有三种不同说法。

| 文件 | 原来对 `review/*/task.md` 的说法 |
|------|------|
| AGENTS.md 权限矩阵 | Dev AI = ❌（禁止） |
| coder.json | `allowed_paths` 包含它（允许） |
| workflow.json | Dev AI 的 input 是它（只读） |

**修改内容**：

| 文件 | 变更内容 |
|------|---------|
| `AGENTS.md` | ① 权限矩阵引入 `R`/`W`/`RW`/`-` 四态（替代 ✅/❌）② 角色描述增加「可读但不可写」段落 ③ 加图例、优先级声明、默认行为声明 |
| `.ai/config/coder.json` | ① 引入 `description` 语义定义 ② `allowed_paths` 只放可写路径 ③ 新增 `read_only_paths` 放只读路径 ④ 补全 5 项职责（与 AGENTS.md 对齐） |
| `.ai/config/tester.json` | 同上改造，QA AI 的 `task.md` 从 forbidden 移到 `read_only_paths` |

**修改后的关键权限交叉点**：

| 路径 | Dev AI | QA AI | 含义 |
|------|--------|-------|------|
| `review/*/task.md` | 只读 | 只读 | 两人都能看任务，都不能改 |
| `review/*/feedback/` | 只读 | 读写 | 只有 QA 能写反馈，Dev 只能看 |
| `review/*/impact.md` | 读写 | 禁止 | 只有 Dev 能写影响评估 |
| `projects/*/src/` | 读写 | 禁止 | 业务代码只有 Dev 能碰 |

**新增规则**：
- 解析优先级：`forbidden > read_only > allowed`（禁止规则永远优先）
- 默认行为：未出现在权限表中的路径，默认禁止所有 AI 访问

---

### 硬伤 3：后端代码纳入权限保护伞

**发现问题**：`projects/*/src/` glob 匹配不到 `server/`、`config/`、`types/`。

**执行操作**：

| 操作 | 详情 |
|------|------|
| 目录移动 | `server/` → `src/server/`、`config/` → `src/config/`、`types/` → `src/types/` |
| 引用修复 | `tsconfig.json`（include 简化）、`ENVIRONMENT.md`（3 处 `cd server` → `cd src/server`）、`docs/02_架构设计.md`（2 处目录结构图 + 代码路径） |

**效果**：一条 `projects/*/src/` 权限规则覆盖全部业务代码——前端、NestJS 后端、Taro 构建配置、全局类型声明。

---

### 硬伤 4：.ai/prompts/ 从空壳到可用

**发现问题**：`coder.json` 和 `tester.json` 引用 `prompt_templates` 路径，但实际文件只含一行标题。

**新增文件**：

| 文件 | 用途 |
|------|------|
| `.ai/prompts/coding/code-style.md` | 代码风格：命名规范、目录组织（前端+NestJS+Python）、导入顺序、API 规范、禁止事项 |
| `.ai/prompts/coding/doc-template.md` | impact.md 和 acceptance.md 的标准化模板 |
| `.ai/prompts/testing/bug-report.md` | QA AI 反馈格式：严重程度定义（BLOCKER/HIGH/MEDIUM/LOW）、轮次规则、升级条件 |
| `.ai/prompts/coding/README.md` | 重写为可用的文件索引 |
| `.ai/prompts/testing/README.md` | 重写为可用的文件索引 |

---

### 硬伤 6：Workflow 从线性到闭环

**发现问题**：8 阶段纯线性流程，没有「测试失败 → 修复 → 再测」的建模。

**修改内容**：

| 文件 | 变更 |
|------|------|
| `.ai/config/workflow.json` | ① 8 阶段合并为 4 阶段（开发实现包含了 impact + acceptance）② 新增 `retry` 配置：`max_rounds=3`，`loop=["测试验证","开发实现"]` ③ 新增 `escalation` 规则 |
| `AGENTS.md` | ① 流程图改版，增加循环箭头 ② 新增「缺陷修复循环」章节 ③ 详细的 round 示例 |

**修改后的流程**：

```
需求分析（人类）
    ↓
开发实现（Dev AI）= 代码 + 文档 + impact + acceptance
    ↓
测试验证（QA AI）= 测试 + 报告 + feedback
    ↓          ↑
    │ 有 Bug → │（最多 2 轮修复复查）
    ↓          └── 第 3 轮仍有 Bug → 升级给人类裁决
验收确认（人类）
```

**retry 配置详情**：

```json
{
  "retry": {
    "max_rounds": 3,
    "loop": ["测试验证", "开发实现"],
    "escalation": {
      "trigger": "第 3 轮测试仍有 BLOCKER 或 HIGH 级别 Bug",
      "action": "暂停任务流转，等待人类负责人裁决"
    },
    "skip_acceptance_on_retry": true
  }
}
```

---

## 宪法健康状态

| 维度 | 改前 | 改后 |
|------|------|------|
| 权限一致性（三文件对齐） | ❌ 矛盾 | ✅ 统一 |
| 权限粒度（读/写分离） | ❌ 只有全或无 | ✅ R/W/RW 三态 |
| JSON 可读性（有语义定义） | ❌ 无解释 | ✅ 有 description |
| 路径覆盖率（src/ 覆盖全部业务代码） | ❌ 漏掉后端 | ✅ 全覆盖 |
| 提示词库 | ❌ 空壳 | ✅ 3 份可用 |
| 工作流建模（含循环） | ❌ 纯线性 | ✅ 含 retry + escalation |
| 默认行为（路径不在表中） | ❌ 未定义 | ✅ 默认禁止 |
| 优先级（规则冲突时） | ❌ 未定义 | ✅ forbidden 优先 |

---

## 仍待处理的遗留事项

| 事项 | 状态 | 说明 |
|------|------|------|
| P01 文档内容 | ⚠️ 未改 | 需求/架构/接口文档内容仍是"代码检测"，后续需重写为"错题本" |
| shared/ 数据协议层 | ⚠️ 仍是空白 | 需要建 `shared/schemas/` 定义跨项目数据模型 |
| shared/ 模板文件 | ⚠️ 缺少 | `shared/templates/` 中没有 task.md 模板 |
| CI/CD 流水线 | ⚠️ 空目录 | `.github/workflows/` 只有 README 占位 |
| Coze 扣子实际能力验证 | ❓ 未知 | 能否操作 Git、能否执行测试——决定 QA AI 验收标准如何定 |

---

## 涉及文件清单

### 修改的文件（11 个）
1. `AGENTS.md`
2. `.ai/config/coder.json`
3. `.ai/config/tester.json`
4. `.ai/config/workflow.json`
5. `.ai/prompts/coding/README.md`
6. `.ai/prompts/testing/README.md`
7. `projects/P01_errlens_app/tsconfig.json`
8. `projects/P01_errlens_app/ENVIRONMENT.md`
9. `projects/P01_errlens_app/docs/02_架构设计.md`

### 新增的文件（5 个）
10. `.ai/prompts/coding/code-style.md`
11. `.ai/prompts/coding/doc-template.md`
12. `.ai/prompts/testing/bug-report.md`

### 移动的目录（3 个）
- `projects/P01_errlens_app/server/` → `projects/P01_errlens_app/src/server/`
- `projects/P01_errlens_app/config/` → `projects/P01_errlens_app/src/config/`
- `projects/P01_errlens_app/types/` → `projects/P01_errlens_app/src/types/`

---

**报告生成时间**：2026-05-23  
**审核执行者**：Dev AI (Trae)