# Engineering Principle Recorder > 工程/执行原则录入器。当用户发现系统应遵守某条原则（工程约束/AI行为规范），自动分类原则类型、写入正确执行层、审计当前违规点、生成修复追踪。区别于 cognitive-extract-principle（后者处理郑总的思维方式原则）。触发词：「立一个原则」「记下这个原则」「这是条工程原则」「以后所有X都要Y」「把这条原则记在相关文档里」「这应该是工程原则」。 - Skill: `tashangkd/engineering-principle-recorder` (Agent Skill) - Install (CLI): `npx skillmds@latest add tashangkd/engineering-principle-recorder` - Raw SKILL.md: https://api.skillmd.com/api/skills/tashangkd/engineering-principle-recorder/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/engineering-principle-recorder --- # 工程/执行原则录入器（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 提供标准输出格式模板