From 352b7813404430a25bd9d20fe2147703ec9251d2 Mon Sep 17 00:00:00 2001
From: zyycn <zyycn@users.noreply.github.com>
Date: Tue, 7 Jul 2026 01:10:02 +0800
Subject: [PATCH] chore: add engineering standards skill

Co-authored-by: Codex <noreply@openai.com>
---
 skills/engineering-standards/SKILL.md         | 119 ++++++++++++++++++
 .../engineering-standards/agents/openai.yaml  |   4 +
 2 files changed, 123 insertions(+)
 create mode 100644 skills/engineering-standards/SKILL.md
 create mode 100644 skills/engineering-standards/agents/openai.yaml

diff --git a/skills/engineering-standards/SKILL.md b/skills/engineering-standards/SKILL.md
new file mode 100644
index 000000000..259d95d79
--- /dev/null
+++ b/skills/engineering-standards/SKILL.md
@@ -0,0 +1,119 @@
+---
+name: engineering-standards
+description: 面向长期维护的工程规范工作流。当用户要求代码审计、问题修复、重构、实现方案、生产问题追溯，或强调代码质量、干净架构、拒绝垃圾代码、禁止兼容写法、先审计再改代码、参考项目对比时使用。
+---
+
+# 工程规范
+
+使用这个 skill 时，先证明当前系统真实行为，再决定是否需要改代码。核心规则：先画出现有证据链，再谈方案。
+
+## 硬门禁
+
+提出方案或动代码前，必须先给出三段内容：
+
+1. 现有机制：入口、调用链、数据变化、数据读取、接口/界面展示路径。
+2. 缺口证据：具体缺失或断裂的环节，并给出源码位置。
+3. 最小改动点：在不绕开现有设计的前提下，能修复问题的最小所有权边界。
+
+在现有链路被追完并证明不足之前，不要引入新的机制、分支或旁路来绕开问题。
+
+## 审计流程
+
+以当前仓库的实时源码为唯一事实来源。只有在当前项目链路已经清楚后，才使用记忆或参考项目。
+
+1. 先确认用户讨论的数据或行为是什么。
+2. 追踪它在哪里产生、转换、持久化、加载和展示。
+3. 同时查主动链路和被动链路。运行时行为要分开检查：触发条件、执行路径、持久化、读取和展示。
+4. 设计前先分类问题所在层级：
+   - 展示层
+   - 接口契约
+   - 持久化层
+   - 运行时行为
+   - 外部依赖
+   - 异步或周期性行为
+5. 说明哪些证据支持该分类，哪些仍未证明。
+6. 排查中发现代码异味、疑似死代码或结构性隐患时，先记录证据，不打断主流程；主问题排查完毕后再汇总报告，并询问是否纳入修复范围。
+
+如果有 `codegraph`，先用它快速定位，再回到源码和测试验证。不要把 codegraph 摘要、记忆、参考项目当成强于当前源码的证据。
+
+## 参考项目
+
+参考项目只能在当前项目证据清楚后，用来理解可能的模式。
+
+除非同时满足以下条件，否则不要把参考项目机制搬进当前项目：
+
+1. 当前项目确实缺少所需行为。
+2. 当前架构存在匹配的所有权边界。
+3. 新设计不会绕开或复制现有链路。
+4. 当前任务范围允许进入实现。
+
+参考项目和当前源码冲突时，以当前源码为准。
+
+## 干净实现标准
+
+优先在现有所有权边界内做最直接、最干净的修复。
+
+- 除非用户明确要求，不要添加兼容代码。
+- 不要用补丁式分支或重复机制掩盖边界不清。
+- 不要用大范围重构掩盖不确定性。
+- 不要为解决局部问题改动无关模块。
+- 只有在确实降低复杂度或符合现有本地模式时，才添加抽象。
+- 必要时可以重构，但重构必须收敛职责、减少分支、让主链路更清晰。
+- 不要用外层绕路掩盖内层问题。
+- 除非证明现有设计不足，不要引入新的执行路径替代原链路。
+
+如果方案会改变语义，动代码前必须明确说明。
+
+## 用户质量要求
+
+默认用户要求严格工程纪律：
+
+- 简单问题先给结论。
+- 审计必须给具体源码证据。
+- 不要做推测性断言。
+- 不要虚构任何事实、数据来源或系统行为。
+- 新项目/新链路不要塞兼容垃圾。
+- 仓库约定测试在测试目录时，不要把测试写进源码模块。
+- 使用代码索引工具辅助理解时，改代码后必须同步索引。
+
+当任务范围被限定为审计、文档、评审或方案阶段时，只交付对应产物，未经要求不实现。
+
+## 动代码前检查
+
+编辑文件前，确认：
+
+1. 当前链路已经端到端追完。
+2. 问题已经按证据分类。
+3. 现有机制不能满足需求，而不是没查到。
+4. 改动点是最小的干净边界。
+5. 测试会通过合适的公开接口或集成测试面覆盖行为。
+
+任何一项缺失，都继续调查，不要实现。
+
+## 收尾检查
+
+结束前确认：
+
+1. 运行格式化和相关测试。
+2. 如果该语言有既定 lint 命令，运行 lint。
+3. 确认没有在应该放测试目录的项目里添加源码内测试。
+4. 确认没有用参考项目模式替代当前项目证据。
+5. 确认没有未经明确批准引入额外分支或旁路设计。
+6. 需要时同步 codegraph。
+7. 总结改了什么、验证了什么、明确没有改什么。
+
+## 必须避免的反模式
+
+不要重复这些错误：
+
+1. 只看一个局部触发点，就断言完整系统行为。
+2. 没有追完已有链路，就新增另一套处理机制。
+3. 没有证明现有机制失败，就用旁路设计绕开问题。
+4. 把参考项目的做法直接搬进当前项目，跳过当前源码证据。
+5. 用补丁式分支或重复机制掩盖所有权边界不清。
+
+正确做法：
+
+1. 先追当前项目已经存在的真实链路。
+2. 证明数据在产生、转换、持久化、读取和展示中的断点。
+3. 以断点为依据选择最干净的修复边界；能局部修清楚就局部修，原链路本身不干净时就重构收敛。
diff --git a/skills/engineering-standards/agents/openai.yaml b/skills/engineering-standards/agents/openai.yaml
new file mode 100644
index 000000000..55dc4345a
--- /dev/null
+++ b/skills/engineering-standards/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "工程规范"
+  short_description: "长期维护的工程规范：证据优先、范围纪律、干净实现与审计工作流。"
+  default_prompt: "使用 $engineering-standards 按工程规范先审计当前代码链路，再提出或实现干净修复。"