随着大语言模型推理与代码生成能力提升，过重的过程编排往往会挤占宝贵上下文，甚至诱导 Agent 倾向于“填满流程模板”而非“恢复系统正确性”。本技能提供按“质量约束优先于过程编排”审查与重构项目 AGENTS.md 的规范方法，将机器可验证的规则沉淀为脚本门禁，保留关键系统不变量、风险升级清单与验证入口表，并明确嵌入式固件场景下的安全底线。
SKILL.md 元数据
---
name: agents-md-quality-constraints
description: >-
[Scope: global] 按“质量约束优先于过程编排”审查、精简或编写项目 AGENTS.md：把可机器验证的规则迁移为脚本/CI 门禁，
保留系统不变量、风险升级清单与验证入口表，删除重复事实和形式化流程模板，并给出嵌入式固件项目的适配边界。
当用户要求优化、精简、审查或新建 AGENTS.md / 项目 Agent 规则，或认为 Agent 工作流过重、规则与仓库事实不一致时使用此技能。
---
1. 适用范围与背景
- 技术方向：
common（通用与工程基建） - 使用范围 (Scope)：
global（适用于所有包含AGENTS.md/ Cursor Rules / Claude Instructions 的软件与嵌入式工程） - 方法论来源：Junsen，《别再教聪明模型做小学数学：从「过程编排」到「质量约束」的 Agent 范式演进》（2026-10-17）。
- 与其它技能的协同：
embedded-six-stage-workflow负责高风险硬件改动的门禁；本技能负责判断哪些规则应交给编译器与检查脚本，哪些必须作为架构不变量留在提示词中。
核心演进观点
- 工作流是在补偿模型当期的不足：模型能力增强后，死板的阶段输出格式与重流程会挤占有限的有效注意力窗口。
- 约束不变量优于规定行动步骤：写清楚“什么不能破坏、什么条件必须满足、什么证据才算完成”，比规定每步先做什么更具鲁棒性。
- 可机器验证的规则移出提示词：交给类型系统、Linter、测试脚本与 CI；
AGENTS.md本质应是“工程地图与安全边界”。 - 调查以建立“最小充分系统模型”为准：不要求扫描全部代码，解释清楚根因与影响边界即可停止探索。
- 人类介入聚焦于不可逆与高风险决策：人机协同的核心是把控不可逆操作与业务折中，而非机械式审批每一步。
2. 核心执行流程
调查仓库事实与已有工具链
│
▼
逐条核对 AGENTS.md 现有规则
│
▼
分类分流：机检迁移 / 不变量保留 / 风险升级 / 流程精简
│
▼
补充「验证入口表」与「调查停止标准」
│
▼
分批落地：先纠正事实与验证入口 → 再迁移脚本门禁 → 最后精简文字
1. 先调查事实，再读规则
- 列出已有的测试、验证脚本、CI 配置、构建命令和工具链安装情况。
- 逐条核对
AGENTS.md中的“当前事实”（例如“没有命令行构建脚本”、“编译器版本”等）与仓库实际是否一致；不一致者作为最高优先级修正项。
2. 规则五分类法则
| 类别 | 判据 | 处理策略 |
|---|---|---|
| 可机器验证 | grep、git diff、编译器、测试、.map 文件能给出确定结论 |
迁移为检查脚本或 CI；AGENTS.md 只保留一句约束加上入口命令 |
| 不可机检的不变量 | 影响系统正确性，但只能靠设计、审查或仪器证明 | 保留，明确写成“不能破坏什么 / 完成需要什么证据” |
| 风险升级 | 不可逆操作、跨模块公共契约变更、需要产品/业务决策 | 保留为显式清单，写明需要人类确认的前置条件 |
| 过程编排 | 规定步骤顺序、阶段输出格式、模板填写要求 | 低风险任务直接删除；高风险任务压缩为通过条件 |
| 重复事实 | 同一事实在 AGENTS.md 多处出现或与权威文档重复 |
只保留一处权威定义，其余改为相对指针引用 |
3. 补齐“验证入口表”
每个入口写明命令、覆盖范围、依赖和不能证明什么，防止 Agent 把仿真通过虚构为实测通过。表中每条命令在写入前必须经过现场实际运行校验。
4. 明确“调查停止标准”
当已有证据足以解释：问题如何发生、根因在哪里、哪些调用方与共享状态受影响、修改边界落在哪里时，即可停止扩大检索；出现新冲突或新证据时再继续补充。
5. 风险分级与决策确认
- 自主完成：可逆、局部、低风险的改动，自主执行并通过对应验证；
- 先通知后执行：影响面较大但行为预期明确的改动，说明影响后再落地；
- 前置确认：高风险、不可逆或涉及核心业务取舍的操作，必须获得确认后方可执行。
3. 嵌入式固件项目的适配边界
强安全审计与不可逆物理场景不能盲目套用纯软件的轻流程。嵌入式固件工程中以下内容严禁精简：
- 硬件依据绝不猜测：引脚定义、寄存器位域、外设复用、电气时序与电平若无数据手册或原理图依据，严禁脑补推测。
- 不可机检的硬件并发风险：ISR/DMA 竞态、时钟树分频、看门狗窗口、掉电恢复策略、Flash/EEPROM 擦写寿命，必须保留设计核对与分级审查。
- 物理不可逆操作：固件实机烧录、整片擦除、标定参数持久化覆写，始终需要明确授权。
- 验证层级诚实区分：静态审查、编译通过、主机逻辑回归、仿真验证、上板实测、逻辑分析仪时序解码及掉电注入必须严格分开报告。
- 工具链现实：要求的编译器（如 ARMCC 5）未安装时，如实标为未验证，不得用宿主编译器或替代工具链冒充通过。
典型嵌入式规则的“机检脚本化”范例
| 原始文字规则 | 迁移后的机器检查方式 |
|---|---|
| 应用层不直接操作外设 | 检查 APP/*.c 中不得包含芯片外设底层头文件（历史例外列入白名单） |
| 驱动层不依赖应用层 | 检查 DRV/* 中不得出现 #include "app_ |
| 厂商库代码原则上不修改 | git diff --name-only 命中厂商库目录时立即告警拦截 |
| 仅在主循环喂狗 | 检查喂狗函数（如 IWDG_ReloadCounter）调用点只允许出现在主循环调度文件 |
| 共享中断只在一处配置 | 搜索 NVIC 中断配置函数调用，确保相同 IRQ 的配置调用点全局唯一 |
| 不提交二进制与编译中间产物 | Git 暂存区检查，拦截 Objects/、*.hex、*.axf、*.map 等文件 |
| 不新增编译警告并核算内存增量 | 运行 Keil 命令行构建并解析 .build_log.htm 与 .map，对比基线，见 keil-armcc-build-analyzer |
| 源码文件统一编码 | 对暂存区改动文件逐个进行 UTF-8 严格解码检查，防止乱码与 BOM 污染 |
4. 验证与交付标准
- 事实可追溯：
AGENTS.md中每一条“当前配置/当前事实”均能在源码、工程文件、CI 脚本或实测记录中找到出处。 - 命令可执行：验证入口表中的命令全部经过实际运行测试；环境依赖缺失时明确写明缺少项及安装指引，而非粗暴删减。
- Diff 纯净性：运行
git diff --check，确保无多余换行符、空白错位或文件编码突变；运行生成的中间缓存（如__pycache__/）交付前清理。 - 交付说明清晰：交付报告列出修正的事实偏差、迁移为机检的规则项、精简的流程段落及未验证项目的具体理由。
参考范例：高质量约束化 AGENTS.md 规范模板 (examples/AGENTS.quality-constraints.md)
以下为兼顾敏捷演进与严格质量边界的标准 AGENTS.md 模板结构，可根据具体项目特点裁剪使用：
# 项目 AGENTS.md 规范
## 核心目标
在保证系统正确性、架构不变量、可验证性、可维护性与项目一致性的前提下，自主推进并完成代码修改。
不为遵守固定流程而制造形式化步骤；依据任务复杂度、影响面与风险等级选择最有效的调查、实现与验证路径。
---
## 1. 修改前建立足够的系统理解
动手修改前，必须建立完成当前任务所需的「最小充分上下文」：
- 定位直接相关的代码入口与核心实现；
- 梳理直接上游与下游调用关系；
- 明确关键数据流、状态转移与核心类型；
- 查阅已有同类实现、公共工具函数与相关测试；
- 核对可能受波及的模块边界与系统不变量。
停止检索标准：当已有证据能够清晰解释问题成因、根因位置、受影响的调用方与状态、需恢复的不变量及修改边界时，即可停止扩大搜索。
---
## 2. 复杂任务的前置安全分析
若任务涉及以下高危场景，在修改前必须明确设计并记录依据：
- 公共接口、协议契约或跨模块共享状态变更；
- 异步并发、中断抢占（ISR）、DMA 缓冲区生命周期；
- 持久化存储（Flash/EEPROM）格式或掉电安全策略；
- 根因复杂或潜在影响边界不清晰。
前置自检清单：
1. 目标行为是什么？非预期行为是什么？
2. 现有实现为何未能满足？修复会否破坏既有契约？
3. 最少修改哪些位置即可达成目的？
4. 如何设计可独立执行的验证，以确保证明修改正确且无副作用？
---
## 3. 坚守架构与系统不变量
修改过程中严禁破坏以下底线：
- 分层边界不倒置（APP 业务不越级操作底层硬件，底层驱动不反向依赖上层业务）；
- 状态机转移必须完备且合法，非法事件具备兜底保护；
- 内存与资源操作保证零泄漏、零越界、对齐合规；
- 涉及时间差值计算必须保证无符号回绕安全。
---
## 4. 验证入口表（可验证性契约）
| 验证类型 | 执行命令 | 覆盖范围 | 前置依赖 | 不能证明什么 |
| :--- | :--- | :--- | :--- | :--- |
| **代码规范与格式** | `npm run lint` / `git diff --check` | 全仓文本格式与规范 | Node.js | 不能证明业务逻辑正确 |
| **主机单元回归** | `python run_tests.py` | 协议解析、状态机转移与边界算法 | Python 3 + GCC/Clang | 不能证明 MCU 硬件时序与真实外设电气特性 |
| **无头固件构建** | `UV4.exe -b Project.uvprojx -j0` | 嵌入式工程编译链接与资源占用 | Keil MDK | 不能证明硬件上板实测功能正常 |
*注：所有命令必须当场实际运行通过，方可记录为验证证据。*
---
## 5. 风险分级与确认授权矩阵
- **自主推进**：纯逻辑修复、单测补充、局部无破坏性重构；
- **提前告知**：影响公共模块但接口兼容的调整、构建脚本优化；
- **必须前置确认**：破坏性接口变更、物理器件擦写、固件烧录、生产配置变更。
核心理念精要：从「过程编排」到「质量约束」的范式演进
根据 Junsen 在 2026 年 10 月发表的技术复盘，AI 编程正在经历从“机械流程驱动”向“工程约束驱动”的范式转移：
- 早期“过程编排”的历史成因： 过去的模型上下文短、容易偏离目标、推理链不稳定，因此工程师被迫设计了冗长的流水线（需求澄清 → 写 Spec → 拆 Task → 逐步出 Plan → 逐句 Review）。这种设计在当时是必要的“拐杖”。
- 能力提升后的边际递减：
在具备深度思考和自主工具调用能力的现代模型中，过多的流程框架反而成为负担：
- 冗长的阶段模板挤占了最宝贵的上下文注意力；
- 模型把算力消耗在“如何填满漂亮的汇报格式”上，而不是“深入分析系统缺陷”；
- 开发者陷入被动审批的思维惰性，丧失了对系统架构的深度审视。
- “质量约束”的核心支撑体系：
- 类型系统与编译器：最强硬的不可逾越红线；
- 自动化检查脚本：将主观的规范（如命名、依赖方向、分层隔离）转化为客观的返回码（Exit Code）；
- 架构不变量：以简练的声明明确指出系统的生命线，留出探索空间；
- 真实环境反馈闭环：以最短路径触发最小测试或构建，用客观执行事实代替主观汇报。