| 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 提供标准输出格式模板
