codeartz-skills

Imported from hanjeahwan/codeartz-skills (AGENTS.md). Install upstream with npx skills add hanjeahwan/codeartz-skills. Copyright stays with the author.

仓库 Agent 协作规范

适用于修改本仓库代码、Skills、references、hooks、测试和说明文档的 agent。

目标：保证事实可信、职责清晰、变更可验证，同时为探索型和对话型 Skill 保留必要的情境判断。

总纲：事实、权限、状态和阶段边界从严；结构、措辞和对话形式按风险选择。

1. 规则强度

• 必须 / 禁止（MUST）：违反后可能造成事实错误、越权、规则漂移、阶段越界或虚假结果。
• 默认 / 应 / 优先（SHOULD）：通常遵守；有明确的可读性、上下文或任务理由时可以偏离。
• 可以（MAY）：可选写法，不作为验收条件。

具体任务要求优先于通用写作偏好。

2. 硬约束

事实与状态

• 必须以当前 checkout、用户明确输入和可验证证据为事实来源。
• 禁止把推断、示例、旧文档或 handoff 直接写成已确认事实。
• 禁止为了填模板而补造内容。
• 用户没有反对某项推断，不等于已经确认。
• 写入、命令或测试失败时，禁止声称已经成功。
• 未运行的验证必须标记为未验证。

需要表达不确定性时，按需使用：

• 已确认：用户明确确认，或存在直接权威证据。
• 暂定：可继续工作的当前解释，但尚未确认。
• 未知：缺少足够信息。
• 待验证：可通过证据、实验或测试判断。
• 待裁决：需要有权者作出范围、价值或权限选择。
• 冲突：有效来源给出不兼容结论。
• 不适用：已经检查，并确认与当前任务无实质关系。

禁止要求每份文档机械包含全部状态。

范围与副作用

• 只修改用户任务授权范围内的文件和行为。
• 禁止覆盖或回退与当前任务无关的现有改动。
• 禁止无声新增自动写文件、自动修改长期规则、自动执行 hook 或其他持久副作用。
• Skill 的持久化行为必须在边界或产物合同中明确说明。
• 用户或工作流未授权持久化时，默认在对话中返回产物。
• 不得把临时文件或调试产物遗留在未约定位置。

单一权威位置

• 同一项可执行规则必须只有一个权威位置。
• 移动规则时，删除旧位置的同义执行版本。
• 其他文件可以引用或概括权威规则，不得复制一份可独立演化的完整规则。
• 行为变化后，必须检查相关测试、README、示例和插件描述是否仍保留旧行为。

阶段与正式产物

仅对具有阶段、模式或状态机的 Skill 应用：

• 阶段切换必须有可判断条件。
• 当前阶段未放行时，禁止把下一阶段正式产物包装成已完成结果。
• 用户要求跳过流程时，可以给出临时草案，但必须标记假设、缺口或未完成状态。
• 下一阶段必须引用上一阶段有效产物，不得自行重写已确认目标或边界。

3. Skill 与 reference

是否拆分

• 简单、短小、没有多阶段分支的 Skill，可以把完整规则保留在 SKILL.md。
• 多阶段、多模式、长检查表、可复用知识或大量示例，应拆到 references/。
• 不得只为目录形式创建空洞 reference。

默认分工

SKILL.md 优先承载：名称与描述、触发与不触发条件、高层路由、全局边界、正式产物概览和 reference 入口。

reference 优先承载：阶段详细执行、检查与完成条件、产物字段、局部例外、判断探针、示例和较长领域知识。

简单规则拆出后反而增加查找成本时，可以保留在 SKILL.md。reference 不应重新定义全局触发和路由。

界面元数据

• agents/openai.yaml 的 display_name 必须使用英文；说明和默认提示遵守项目语言规则。

渐进加载

• 默认只加载当前任务和当前阶段需要的 reference。
• 为判断接口兼容性，可以读取相邻阶段的简短输入契约、输出契约或共享 schema。
• 未正式路由到下一阶段前，不执行下一阶段步骤，不生成其正式产物。
• 禁止为了提前准备一次性加载所有长 reference。
• 相关文件都很短且合并读取能减少重复时，可以一次读取。

多阶段手册

可比较的阶段手册应共享必要的顶层接口，例如目标、输入、执行、完成或返回状态、产物和禁止。

阶段性质不同，可以采用不同内部结构。禁止为形式一致添加无意义章节。

4. 指令写法

简单规则

• 一个条件只对应一个清晰后果时，可以写成一句完整规则。
• 简单条件、动作和禁止不必机械拆成多个槽位。
• 一条规则应能在附近上下文中独立判断，不要求脱离全文仍成立。

复杂分支

出现互斥后果、易遗漏例外、高风险副作用，或 eval 已证明会漏执行时，应显式拆分。

按需使用：检查项、放行条件、失败条件、处理方式、回退条件、待裁决项、禁止。

不要求每个分支使用全部槽位。

结构与语言

• 默认将规则控制在零到两层；第三层可用于短字段、状态、模板或示例。
• 连续出现第四层及以上规则树时，应改为表格、命名分支、独立章节或 reference。
• 代码块、目录树和数据结构示例不计入嵌套限制。
• 默认按“目标或范围 → 执行 → 完成条件 → 限制与输出”组织。
• 同类文档保持术语和顶层接口一致，不要求逐标题完全同构。
• 使用可执行动词，明确对象、边界和失败处理。
• 删除语义重复但措辞不同的规则。
• 示例只用于消除歧义，不得替代规则。
• 面向 agent 的自然语言默认使用中文；协议字段、命令、代码符号和专有名词保留原文。

5. 对话与正式产物

探索型对话

• 苏格拉底式、探索型或诊断型 Skill 应规定语义最低要求，不应默认强制每轮使用固定栏目。
• 对话可以按情境选择复述、区分、反例、张力、假设或判断探针。
• 没有实质变化时，不要为了模板重复完整状态表。
• 用户无法回答开放问题时，可以改用具体情境、对照选择或反事实探针。

正式产物

• 需要被后续阶段、其他 agent 或未来会话引用的产物，应明确字段、状态、版本和完成条件。
• 正式模板必须允许“未知”“待验证”“待裁决”和“不适用”。
• 路径仅在用户、Skill 合同或宿主工作流已明确时才是强制项。

6. 编辑流程

Skill 行为工程流程

新建 Skill，或修改 Skill 的触发、路由、决策分支、副作用、正式产物或失败处理时，必须按以下顺序执行。纯错别字、链接和不改变行为的格式调整不适用。

1. 建立现实风险矩阵

先从真实使用者和生产环境出发列出行为可能性，再设计实现。矩阵至少使用以下字段：

• 至少检查正常输入、信息不完整、相互冲突、用户未确认、一次性要求、长期规则、无写入权限、工具失败、超时、并发、重试和脏状态。
• 只保留会改变行为或风险的组合；等价分支合并，不为填表枚举无意义笛卡尔积。
• 某个维度不适用时记录原因，不得静默遗漏。

2. 把矩阵转成 live scenarios

• 每个高风险分支、决策边界和已知失败路径必须映射到一个 live scenario；等价分支可以由同一场景覆盖。
• 每个场景必须写明输入状态、预期动作、禁止动作和可观察证据。
• Target Agent 只接收现实用户请求、场景工作区和完成任务所需的原始上下文；禁止向其提供风险矩阵的预期行为、judge criteria、judge prompt、疑似缺陷、预期修复或既往失败诊断。
• 用户真实提供且会改变执行结果的权限、范围、业务目标和约束必须保留，不得为了避免答案泄漏而删除必要输入。
• 信任通过结果前，对照 prompt 与 criteria；prompt 直接陈述了被评行为且该陈述不是必要用户输入时，先删除提示。已有 Skill 重跑失败基线；新建 Skill 在实现完成后重跑受影响场景。
• smoke 覆盖主路径与最关键边界；full 覆盖冲突、失败、恢复、权限和宿主差异。
• 重构或修改已有 Skill 行为时，先运行能复现当前问题的场景并保存失败证据；无法建立基线时标记原因。
• 新建 Skill 不运行失败基线；先建立风险矩阵和 live scenarios，再实现权威核心。
• 禁止用关键词、固定措辞或只匹配最终答案的断言代替行为验证。

3. 实现或重构权威核心

• 新建 Skill 根据风险矩阵和场景边界，在所有相关路径共享的权威决策点实现行为。
• 重构或修改已有 Skill 时，根据失败证据定位表象、直接原因和系统性根因。
• 权威决策点包括 SKILL.md 路由、阶段 reference、hook runtime 或共享验证器。
• 禁止只修改 scenario、judge criteria、示例或最终提示词来满足评测；行为必须由权威核心承载。
• judge 误判时收紧场景标准，使其对齐已有行为合同；不得降低原本有效的质量要求。

4. 运行验证闭环

• 先运行格式、lint、typecheck 和相关静态测试，再使用仓库 live-eval runner 的当前默认拓扑运行定向场景。
• 可独立执行的场景应并发运行；共享可变状态或供应商限流要求串行时，记录原因与并发上限。
• 失败时区分核心实现、scenario、judge、测试框架和环境问题，只修复证据指向的层级，然后重跑失败场景和受影响回归集。
• 完成报告必须列出矩阵覆盖、scenario 映射、核心修改、测试结果、未验证项和剩余风险。

以下条件全部满足后，才能声明 Skill 行为变更完成：

• 现实风险矩阵中的行为分支均已覆盖，或明确记录不适用与未覆盖原因。
• 高风险矩阵行已经映射到 live scenario。
• 新建 Skill 的核心实现与风险矩阵、场景边界一致；已有 Skill 的核心修改与失败证据指向同一权威决策点。
• 静态测试和定向 live eval 已实际运行且结果可核对。

编辑前

• 读取适用的 AGENTS.md、目标文件、相关 reference、测试和 README 描述。
• 确认修改属于结构重排、语义修正、产品行为变化或兼容性修复。
• 检查工作区现有改动，避免用旧稿覆盖进行中的工作。

编辑时

• 做满足目标所需的最小完整改动，不扩大到无关 Skill、hook 或插件。
• 纯结构重排应保留已验证的行为语义。
• 产品目标或行为明确变化时，可以重写或删除旧规则，不要求保留原句。
• 大规模或高风险迁移应建立临时清单，标记“保留、移动、精化、替换、删除”。

编辑后

• 搜索旧术语、旧路径、重复规则和失效示例。
• 删除临时文件并检查最终 diff，确认没有无关改动。

7. 验证

验证强度与改动风险匹配：

• 纯说明文案：格式、路径与术语、最终 diff。
• Skill 触发、路由、规则或产物变化：相关场景测试；可用时运行定向 live eval。
• TypeScript、脚本或测试框架变化：格式、lint、typecheck、相关测试。
• 插件清单、安装或打包变化：对应 dry run、安装路径或清单验证。
• Agent Evolve 自动触发、模式路由或 hook 上下文变化：必须加载当前本地 plugin 并触发真实 hook 的 live test。

仅复制 Skill 的 live test 不能替代 Agent Evolve plugin hook live test。环境无法运行时，报告为未验证并说明阻塞原因。

常用命令：

npm run format:all
npm run lint
npm run typecheck
npm test
npm run eval:live:check
npm run eval:live

• 优先运行与改动范围相关的最小验证集。
• 只有准备接受全仓库格式变化时，才运行全量格式化。
• npm run lint:all 会自动修复全仓库；没有明确需要时不要运行。
• 测试失败时，区分此次改动、环境问题和仓库既有失败。
• 禁止为了得到绿色结果删除、放宽或绕过有效测试。

8. 完成报告与自检

完成任务时报告：修改文件、用户可感知的行为变化、验证结果、未验证项、已知限制或待裁决项。