engineering-principle-recorder

name	engineering-principle-recorder
description	工程/执行原则录入器。当用户发现系统应遵守某条原则（工程约束/AI行为规范），自动分类原则类型、写入正确执行层、审计当前违规点、生成修复追踪。区别于 cognitive-extract-principle（后者处理郑总的思维方式原则）。触发词：「立一个原则」「记下这个原则」「这是条工程原则」「以后所有X都要Y」「把这条原则记在相关文档里」「这应该是工程原则」。

工程/执行原则录入器（engineering-principle-recorder）

核心目标：一条原则被说出来 → 两周后，另一个 AI session 自动被它约束。 这不是「记在本子里」，而是「写入 AI 每次必读的执行层」。

---

认知根

认知根：_内部总控/认知结构/L1_系统性文档/系统架构思维维度/Skill体系设计原则_v1.0.md 关联：本 Skill 维护「Skill 体系执行约束」的完整性，与设计原则中「执行层」概念直接对应。

---

两类原则的本质区别（AI 执行者必须先理解）

类型	内容	走哪里
认知原则	郑总如何思考/判断（「先从小点出发升维」）	→ cognitive-extract-principle → L1.5
执行原则	AI系统/代码应如何运行（「LLM调用不截断」）	→ 本 Skill → Role Skill / Rule / 追踪台

---

知识导航表（执行前按顺序读取）

层级	文档	读取目的
D0	_内部总控/元项目导航.md	提取当前活跃项目路径，用于 Step 2-D 的代码搜索目录和追踪台路径
①	.cursor/skills/skill-index/SKILL-INDEX.md	确认 Step 2-C 中相关 Role Skill 的实际文件路径

---

激活后立即执行

Step 0  【读取必要上下文】（静默完成，不向用户输出）
        Read: _内部总控/元项目导航.md
        → 记录当前活跃项目名称 + 代码路径 + 追踪台路径
        Read: .cursor/skills/skill-index/SKILL-INDEX.md
        → 记录 Role Skill 的实际文件路径

Step 1  【精确化原则 + 类型分类（必须与用户交互完成）】

        ⚠️ 执行铁律：先确认原则精确表述 + 分类，再执行写入。禁止跳过。
        ⚠️ 分类完成后，无需用户再次指示，立即执行对应的 Step 2。

        Step 1-1  精确化原则表述
                  向用户确认：「我理解您要立的原则是：[提炼后的精确表述]。
                  判断标准是：[什么情况算违反了此原则]？」
                  → 等待用户确认后，以确认版本作为写入内容，不用原话

        Step 1-1.5  【等效三问声明（A1.9 门禁前置满足）】
                    本 Skill 在 Step 1 已等效完成 skill-rule-修改规范 三问：
                    ① 根因 = Step 1-1 用户确认的原则内容（为什么要改）
                    ② 影响范围 = Step 1-2 分类后确定的写入目标文件
                    ③ 验证方法 = Step 3 覆盖报告中的可靠性评估
                    → AI 执行时在 Step 1 末尾内部记录：「A1.9 三问已完成，可继续写入 .cursor/ 文件」
                    → 不需要再次触发 skill-rule-修改规范 的完整流程

        Step 1-2  类型分类

                  ─── 类型 A：认知/思维原则 ───
                  判据：原则描述的是「郑总如何思考/判断/分析问题的方式」
                  示例：「我倾向于先从小点出发」「推断前先验证」
                  处理：告知用户「这条原则描述的是您的思维方式，应通过
                        cognitive-extract-principle 流程录入到 L1.5 底层原则库。
                        本 Skill 在此停止——请您说『提炼原则』以激活该流程。」
                  → 本 Skill 在此终止，不执行 Step 2 和 Step 3。

                  ─── 类型 B：AI 行为约束 ───
                  判据：原则描述的是「AI 执行任务时如何使用工具/读文档/调用资源」
                        （不涉及代码设计，只约束 AI agent 的操作方式）
                  示例：「读文档不截断，分次读但不遗漏」
                        「连接服务器前先确认是哪台机器」
                  → 标记 B = true，进入 Step 2-B

                  ─── 类型 C：工程设计原则 ───
                  判据：原则描述的是「代码/LLM调用/系统架构应如何设计」
                  示例：「LLM 调用上下文不截断，qwen3.5plus 256K 够用」
                        「认证必须复用现有服务，不得重新实现」
                  → 标记 C = true，进入 Step 2-C

                  ─── 类型 D：当前代码存在违规 ───
                  判据：用户明确指出「现在代码里已有违反这条原则的地方」
                        OR 本 Skill 执行 Step 2-C 后判断极可能有历史违规
                  → 标记 D = true，在 Step 2-C 完成后进入 Step 2-D

                  ⚠️ 多类型并发：B+D 和 C+D 都是合法组合，逐类处理，不跳过任何一类
                  ⚠️ 若分类不确定 → 问用户：「这条原则是关于AI的操作方式（B），
                     还是代码的设计方式（C），还是两者都是？」

                  ─── 与相似 Skill 的区分 ───
                  「这里有个规范问题/这次违反了规范」（已有规范被违反一次）→ project-convention-resolver
                  「要立一条新原则」（原则本身尚不存在）→ 本 Skill
                  若不确定 → 问用户：「是要修复这次违反，还是建立一条新规范？」

Step 2-B  【AI 行为约束 → 写入执行层（B类）】（仅当 B = true）

          ⚠️ 必须实际工具调用写文件，禁止只口头描述「已录入」

          B-1  判断写入目标（判据如下）
               普遍约束（对所有角色/所有会话均生效）→ session-bootstrap.mdc
               特定角色约束（仅当某 Role Skill 激活时生效）→ 对应 Role Skill 的约束节
               判断标准：「去掉所有角色限定词，这条原则还成立吗？」
               → 是 → 普遍约束 → session-bootstrap
               → 否 → 特定角色约束 → 对应 Role Skill

          B-2  Read 目标文件（必须先读后写）

          B-3  按 skill-rule-修改规范 备份
               Shell: cp [目标文件] [history/目录/文件名_vX_YYYYMMDD_before_principle.md]

          B-4  StrReplace 写入
               → 在目标文件「约束」节或等效节末尾追加：
               `- [原则标题]：[精确描述]（来源：engineering-principle-recorder，[日期]）`

          B-5  StrReplace 追加变更记录到文件末尾

          B-6  输出：「[B类] 已写入 [文件路径] / [节名称]」
               → 完成后无需等待，继续检查是否有 D = true

Step 2-C  【工程设计原则 → 写入 Role Skill 第一性原理（C类）】（仅当 C = true）

          ⚠️ 必须实际工具调用写文件，禁止只口头描述「已录入」

          C-1  识别最相关的 Role Skill（可多选，用 SKILL-INDEX.md 确认路径）
               LLM/AI调用/Prompt → `.cursor/skills/role-AI工程师/SKILL.md`
               部署/运维/服务器 → `.cursor/skills/role-DevOps/SKILL.md` 或 `REFERENCE.md`
               前端实现 → `.cursor/skills/role-前端开发/SKILL.md`
               后端实现 → `.cursor/skills/role-后端开发/SKILL.md`
               技术架构 → `.cursor/skills/role-技术架构师/SKILL.md`
               所有角色通用 → 同时写 session-bootstrap（B类处理）

          C-2  Read 目标 Skill 文件
               → 找「第一性原理」节或等效约束节
               → 若无该节 → 在 Skill 文件正文开头（---分隔符之后）新建「## 第一性原理」节
               → 检查是否有语义相近的已有原则（如有矛盾 → 暂停，告知用户）

          C-3  按 skill-rule-修改规范 备份 + StrReplace 写入 + 追加变更记录
               写入格式：`- [原则标题]：[精确描述]（来源：engineering-principle-recorder，[日期]）`

          C-4  输出：「[C类] 已写入 [文件路径] / [节名称]」
               → 完成后无需等待，继续检查是否有 D = true
               → ⚠️ 若任一目标文件写入失败：
                  - 在 Step 3 报告中标注「未覆盖：[文件路径]（写入失败）」
                  - StrReplace 追加到 PENDING-EXPERIENCES.md：
                    `| [今日] | engineering-principle-recorder | 步骤偏差 | 原则[名称]写入[文件]失败，需补录 | 🔲 待处理 |`
                  - 不静默跳过，不假装写入成功

Step 2-D  【代码违规审计 + 追踪（D类）】（仅当 D = true）

          D-1  构建搜索模式（必须至少 3 个候选词，覆盖不同代码写法）
               基于原则语义推导代码中可能的违规模式，例如：
               「不截断」原则 → 搜索词：`[:6000]` `[:3000]` `[:500]` `max_tokens=` `content[:`
               「必须复用认证」原则 → 搜索词：`jwt.encode` `create_token` `def authenticate`
               ⚠️ 不同原则需不同搜索词，必须基于原则语义推导，不可照抄示例

          D-2  执行代码搜索
               Grep: [当前项目代码目录]（从 Step 0 的元项目导航获取路径）
               → 找出语义违规位置（非机械匹配，需要 AI 判断）
               → 区分「日志打印截断」（[:120] 等，无害）vs「LLM输入截断」（有害）

          D-3  写入技术问题追踪台
               Read: [项目路径]/技术架构师/技术问题追踪台.md
               → 对每个违规位置，StrReplace 追加一条 issue：
               格式：| P1 | [日期] | [文件路径:行号] | 违反「[原则名]」：[具体描述] | 🔲 待修复 |

          D-4  输出违规清单给用户：
               「发现 N 处违规（已记录到追踪台）：
               1. [文件:行号] — [描述]
               ...
               是否立即触发 bug-fix-loop-coordinator 修复？」
               ⚠️ 等待用户回复后继续执行 Step 3（无论用户如何回答，Step 3 必须执行）

Step 3  【输出覆盖报告】（所有工具调用完成后才执行，禁止提前输出）

        ⚠️ Step 3 是强制步骤，无论走了哪些 Step 2，都必须执行

        输出格式：
        ────────────────────────────────────────────
        ✅ 原则录入完成

        原则名称：[提炼后的标题]
        原则内容：[精确描述，含判断标准]

        执行层覆盖：
        [B类] [文件路径] / [节名称]：alwaysApply → 每次会话强制生效（高可靠）
        [C类] [文件路径] / [节名称]：角色激活时必读（中高可靠）
        [D类] 发现 N 处历史违规 → 已记录到 [追踪台路径]

        可靠性评估：
        - [当前录入方式] → [可靠性等级]
        - 如需最高可靠性建议：[具体建议，如「也写入 session-bootstrap」]
        ────────────────────────────────────────────

---

常见失败模式（AI 执行者必须知道）

失败模式1：分类完成后停止，不执行 Step 2
  → 根本原因：Step 1 输出分类结果后像任务完成，等待用户
  → 预防：Step 1 末尾明确「无需用户再次指示，立即执行 Step 2」

失败模式2：只口头说「已录入」，没有实际工具调用
  → 根本原因：AI 混淆「输出报告」和「执行写入」
  → 预防：Step 3 在「所有工具调用完成后才执行」，任何 Step 2 未完成前不输出报告

失败模式3：Step 2-D 「等待用户」后跳过 Step 3
  → 根本原因：等待用户被视为任务终止信号
  → 预防：D-4 明确「无论用户如何回答，Step 3 必须执行」

失败模式4：只写一个地方，漏掉其他相关 Role Skill
  → 根本原因：Step 2-C 的 C-1 选了最明显的一个就停
  → 预防：C-1 遍历所有相关 Role Skill，不只选第一个

失败模式5：D 类搜索词太窄，漏掉真实违规
  → 根本原因：从原则语义到代码模式的映射太浅
  → 预防：D-1 至少 3 个候选词，覆盖不同编码习惯

---

注意事项

• 这不是认知体系 Skill：认知原则走 cognitive-extract-principle，本 Skill 只处理执行约束
• 写入即承诺：写入的原则代表 AI 未来被此规则约束，写前必须确认原则内容准确
• D 类不自动修复：违规审计结果告知用户，由用户决定是否触发 bug-fix-loop-coordinator
• 多类逐类处理：不因「已处理 C 类」就跳过 D 类审计

---

变更记录

v1.0 — 2026-03-24 — 初始创建

根因：现有 Skill 体系缺少「工程/执行原则录入」机制。用户提出原则时，系统只能走认知路径 （L1.5）或完全不处理，无法将原则写入 AI 每次执行时必读的执行层（Role Skill / Rule）。

产品定义草稿：.cursor/skills/skill-designer/draft-engineering-principle-recorder.md

设计决策：

• 与 cognitive-extract-principle 互补，不重叠（认知原则 vs 执行约束）
• 写入目标：Role Skill 第一性原理节 / session-bootstrap / alwaysApply Rule（视类型而定）
• D 类违规审计不自动触发修复，保留用户决策权
• Level 3 集成型（依赖 cognitive-extract-principle / skill-rule-修改规范 / issue-tracker 格式）

关卡A修复（来自 skill-simulator 报告）：

• 修复 #1：A 类路由明确说「本 Skill 停止，用户手动触发 cognitive-extract-principle」
• 修复 #2：B-3 备份引用 skill-rule-修改规范
• 修复 #5：D 类说明可与 B 或 C 并发（B+D、C+D 均合法）
• 修复 #6：B-1 增加「普遍约束」判定标准
• 修复 #7：Step 0 说明读取文件的具体用途
• 修复 #9：Step 1-1 增加精确化原则表述步骤
• 修复 #10：C-2 增加「检查是否有语义相近的已有原则（若矛盾则暂停）」
• 修复 #13/#14：触发词去掉「记在相关文档里」「这是个原则」，改为精确表述
• 修复 #15：Step 1 末尾增加与 project-convention-resolver 的区分说明
• 修复 #16：Step 1 末尾加「无需用户再次指示，立即执行 Step 2」
• 修复 #17：D-4 加「无论用户如何回答，Step 3 必须执行」
• 修复 #8：Step 3 提供标准输出格式模板