# Project Convention Resolver

> 项目规范问题自动修复 Skill。当用户指出项目内的规范偏差时，自动分类问题类型，路由到对应角色Skill执行修复，并通过verifier验证修复效果。类比产品侧「问题追踪+修复」的完整闭环，是项目内规范问题的「接收→分类→执行→验证」一体化机制。触发词：「这里有个规范问题」「这不符合规范」「规范偏差」「按规范修复这里」「这里违反了规范」「规范不对」「帮我修复规范问题」。注意：与 issue-tracker 的区别——后者只记录不执行；本 Skill 记录并自动路由执行。

- Skill: `tashangkd/project-convention-resolver` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tashangkd/project-convention-resolver`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tashangkd/project-convention-resolver/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: TashanGKD (https://skillmd.com/u/tashangkd)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tashangkd/project-convention-resolver

---


# 项目规范问题自动修复（project-convention-resolver）

> 定位：项目内规范问题的「接收 → 分类 → 路由执行 → 验证 → 归档」一体化 Skill
>
> 类比关系：
> - issue-tracker → 记录问题（不执行）
> - **project-convention-resolver → 记录 + 自动路由执行 + 验证**
>
> 强绑定 Rule：R2 NO_FABRICATION / R3 READ_FIRST / R7 CLOSED_LOOP_REQUIRED

---

## 规范问题分类（五类）

```
A 类：产品规范偏差
  → 功能不符合产品定义中的闭环设计
  → 动线缺失入口/出口
  → 双层设计缺失（只有人层没有智能体层，或反之）
  → 产品文档描述与实际不符

B 类：技术架构规范偏差
  → 接口设计不符合技术架构.md 规范
  → 模块边界不清晰，违反关注点分离
  → 跨模块耦合过紧，扩展性风险
  → Schema/数据模型与规范不一致

C 类：代码规范/实现偏差
  → 命名规范违反（snake_case/camelCase 混用等）
  → 缺少必要的错误处理或测试
  → 安全漏洞（注入/越权/硬编码密钥）
  → 与产品文档描述不符的实现

D 类：文档规范偏差
  → 文档结构不符合项目规范（缺变更记录/版本号等）
  → 多个文档内容漂移（同一内容在不同文档中描述不一致）
  → README 与实际代码状态不符

E 类：Skill/Rule 规范偏差
  → Skill 描述不准确 / 触发词不对
  → Rule 有冲突 / alwaysApply 叠加矛盾
  → Skill 与实际行为不一致
```

---

## 激活后立即执行

```
Step 1  记录问题（R2：必须基于用户实际描述）
        调用 issue-tracker：
        - 如果是产品设计类 → 写入 产品经理/产品问题追踪台.md
        - 如果是技术实现类 → 写入 技术架构师/技术问题追踪台.md
        - 如果是 Skill/Rule 类 → 写入 .cursor/skills/skill-index/PENDING-EXPERIENCES.md

Step 2  Read 相关文档（R3 READ_FIRST）
        根据问题类型读取必要的上下文：
        A 类 → Read: 产品经理/产品定义.md
        B 类 → Read: 技术架构师/技术架构.md
        C 类 → Read: 被报告的代码文件（具体路径）
        D 类 → Read: 被报告的文档文件
        E 类 → Read: 被报告的 SKILL.md 或 .mdc 文件

Step 3  分类 + 确认修复方向
        向用户确认：
        「检测到 [X类] 规范问题：[问题描述]
          修复方向：[一句话说明]
          将调用：[对应角色 Skill / 工具]
          
          [确认，立即修复] [调整方向后修复] [只记录，暂不修复]」
        
        若用户选择「调整方向后修复」：
        → 等待用户说明调整内容
        → 重新展示调整后的修复方向
        → 再次确认后再执行
        
        不允许静默执行修复（规范修复可能有误判，必须用户知情）

Step 4  路由执行（按分类路由到对应角色 Skill）
        
        【A 类 → 按 role-产品经理 激活协议执行】
        将「规范问题描述 + 相关产品定义章节内容」作为本次 PM 任务的上下文
        按 role-产品经理 的步骤修复产品定义文档或设计逻辑
        
        【B 类 → 按 role-技术架构师 激活协议执行】
        将「规范问题描述 + 相关架构文档章节」作为上下文
        修复技术架构.md，若涉及产品意图，必须先回 PM 确认
        
        【C 类 → 按 role-后端开发 或 role-前端开发 激活协议执行】
        将「规范问题描述 + 具体代码文件路径 + 违反的规范条目」作为上下文
        修复代码后自动触发「Bug 修复后强制验证闭环」（调用 /verifier）
        
        【D 类 → 按 doc-consolidator 激活协议执行】
        将「规范问题描述 + 涉及的文档文件」作为上下文
        整合/修复文档，确保单一真源
        
        【E 类 → 加载 skill-rule-修改规范，强制三问+备份+修改+变更记录】
        E 类不允许直接修改，必须先回答三问，再备份，再修改

Step 5  验证修复效果（R7 CLOSED_LOOP_REQUIRED）
        
        C 类（代码修复）：
        → 自动调用 /verifier，传入原问题描述作为验证场景
        
        A/B/D/E 类（文档/规范修复）：
        → 人工确认：「已完成修复，请确认以下变更是否符合预期：[变更摘要]」
        → 等待用户确认
        → 若本次修复来源为 skill-system-health-check 报告 → 修复完成后，告知：「建议重新运行 skill-system-health-check 验证该问题已消解」

Step 6  归档关闭
        → 更新追踪台对应条目状态为「已修复（含修复说明）」
        → 告知用户：「规范问题已修复并验证，追踪台已更新。」
```

---

## 路由决策树

```
用户报告规范问题
  ↓
判断问题类型
  ↓
├── 涉及产品功能/用户动线/闭环 → A类 → role-产品经理
├── 涉及接口/架构/模块边界 → B类 → role-技术架构师
├── 涉及代码文件 → C类 → role-后端/前端 → verifier
├── 涉及文档组织/版本/内容 → D类 → doc-consolidator
└── 涉及 Skill/Rule 文件 → E类 → skill-rule-修改规范
```

---

## 常见失败模式

**失败模式1**：用户描述的「规范问题」实际上是「功能需求」，而不是现有规范的偏差
→ 预防：Step 3 确认时，区分「当前已有规范要求X，实现做了Y」vs「希望新增规范要求Z」
→ 如果是新需求 → 路由到 role-产品经理 但不走修复路径，走功能设计路径

**失败模式2**：A/B 类规范修复后，未同步检查是否引起连锁影响
→ 预防：B 类技术架构修复后，提示「架构变更可能影响已有代码，建议运行 role-测试工程师 关卡C」

**失败模式3**：E 类 Skill/Rule 修复被静默执行，未通过三问+备份
→ 预防：E 类强制要求先加载 skill-rule-修改规范，不允许跳过

---

## 与现有组件的关系

| 组件 | 关系 |
|---|---|
| `issue-tracker` | 本 Skill 先调用 issue-tracker 记录，再继续执行（issue-tracker 是本 Skill 的 Step 1）|
| `role-产品经理` | A 类问题的执行 Skill |
| `role-技术架构师` | B 类问题的执行 Skill |
| `role-后端/前端开发` | C 类问题的执行 Skill |
| `doc-consolidator` | D 类问题的执行 Skill |
| `skill-rule-修改规范` | E 类问题的执行 Skill（不绕过，必须经过）|
| `verifier` | C 类代码修复后的验证 |
| `architecture-gap-mapper` | B 类问题分析时可选调用 |

### v1.0 → v1.1 — 2026-03-22 — Step 5 E类补修复后重验证建议（GAP-SK017-2 修复）

**根因**：scenario-sandbox-builder Phase 2 验证（SK-017沙盘）发现：Step 5 A/B/D/E类修复完成后只做人工确认，缺少「修复后重新运行 skill-system-health-check」的闭环验证步骤。导致Skill体系健康检查发现的P0问题修复后无法自动验证是否真正消解。

**修改内容**：
- 修改：Step 5 A/B/D/E类 → 在「等待用户确认」后追加：若修复来源为 skill-system-health-check 报告，建议修复完成后重新运行健康检查验证
- 备份路径：`history/SKILL_v1.0_20260322_before_sk017b.md`

**验证方法**：E类修复完成后，Skill 应提示「建议重新运行 skill-system-health-check 验证该问题已消解」
**验证状态**：🔵 待验证

---

## 注意事项

- **Step 3 必须等用户确认**：不允许静默执行修复，规范修复可能有错误判断
- **E 类不能绕过 skill-rule-修改规范**：Skill/Rule 修改的三问+备份是强制要求
- **B 类架构修复必须回 PM 确认**：技术架构变更可能影响产品定义，必须 PM 知情
- **C 类代码修复后强制 verifier**：遵循 role-后端/前端开发 的「Bug 修复后强制验证闭环」规则

---

## 变更记录

### v1.0 — 2026-03-19 — 初始创建

**根因**：项目内规范问题缺少「接收→分类→路由执行→验证」的完整链路。issue-tracker 只记录不执行，规范修复依赖用户记忆力手动触发对应角色 Skill。本 Skill 补完这个链路，使项目规范问题的处理与 Skill 体系自驱机制对等。

**强绑定 Rule**：R2 NO_FABRICATION / R3 READ_FIRST / R7 CLOSED_LOOP_REQUIRED

**验证状态**：🔵 待验证（关卡A/B/C 已通过设计阶段模拟）