ai_soc_sw/reports/quality-reports/framework-review-2026-05-23.md

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 配置详情：

{
  "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)