我整理的编程 Skills

---
name: ajiang_feature_iteration
description: 根据用户任务实现软件新功能或迭代已有功能，优先打通最小完整路径，并从实际入口验证用户可观察结果。
license: MIT
---

# 从用户任务到最小实现

## 定义可观察结果

把需求落成“什么人在什么条件下做什么动作，应观察到什么结果”。有现成失败、截图或参考实现时读取它；明确目标项目与参考材料的身份，防止把参考仓库改了。

读取项目规范、README 和相关脚本，确认修改范围，再从实际入口找现有链路和可复用模块；复用前检查其真实契约，不凭命名推断。需求不明确时先推进不依赖该信息的调查，再询问影响结果的关键差异。无须为每次小改写一份规格。

## 最小纵向切片

优先打通一条完整用户路径：输入 → 状态/业务执行 → 实际输出，而非铺满所有抽象层再做演示。沿用现有栈和结构。记录必要行为与本次不涵盖的需求，不擅自扩展成平台重建。

对比可获得的参考实现时给出设计前提、值得复用的部分与应保留的现有能力；没有源码就只对可观察行为做判断。参考代码是证据，不意味着自动迁移其技术栈。

修改涉及配置、事件、provider、存储或进程边界时，从实际生产者跟到消费者，检查来源、优先级、缺失状态、错误传播和恢复行为，并用对应负向场景验证。触及支持语言、主题或平台时覆盖相应变化；项目不支持的能力不因本流程变成新需求。

## 对结果验证

从项目真实入口执行最小用户任务，检查实际输出或持久化状态。按改动加入关键失败或边界场景，运行现有相关检查。开始时已失败的检查记录为基线，不能把它们静默忽略或归因于本次代码。

本次改动涉及外部服务时，验证请求、返回和实际消费者之间的行为。无法访问服务时完成内部检查，并注明尚未验证的外部行为。检查不会抓住错误实现时，改进断言。

本次新增问题必须处理，无关旧问题记录后续。复杂/高影响变化或用户要求独立 review 时，给独立审查者任务、验收、目标版本和原始事实，不附预设结论；每条发现必须有触发条件与实际后果，逐条核验后再修复。普通小修改可直接交付。

## 完成与连续迭代

功能合入目标分支后，按同一用户路径复测，确认最终集成状态仍满足验收。

下一轮或另一会话接手时保留：用户结果、当前版本、有效配置、已验证内容、已排除假设的适用条件、剩余问题及允许的下一步。

需要多轮迭代或交接时，可按 [功能迭代记录](assets/task-record.md) 保存目标、实现路径、验收和下一步。

---
name: ajiang_debugging
description: 排查软件故障：区分现象与归因，建立修前失败证据和假设实验，最小修复后按原用户流程验证。适用于原因不明、环境相关或修后仍复现的 bug。
license: MIT
---

# 证据驱动排障

目标是恢复用户原来失败的任务，并让结论与实际证明的范围一致。

## 固定问题与基线

- 区分报告中的可观察现象、预期行为和归因猜测。报告者提供的是有价值的线索，猜测需要实验核验。
- 确认待修改仓库、实际工作区、版本/commit 与启动入口；参考仓库只作为参考。记录与问题有关的环境、有效配置、输入规模和历史状态，敏感值只记录配置是否存在或脱敏身份。
- 尝试从用户入口复现，保存准确步骤、错误与预期结果。能安全建立修前失败的自动回归时优先建立；简单问题不必生成额外文档。

## 选择有区分力的实验

不要只寻找支持第一个解释的证据。对竞争假设设计实验，每次尽量改变一个关键条件。沿调用链、配置优先级、状态生命周期及数据规模定位实际差异。

复杂调查可在任务工作目录维护表格：

| 假设 | 可区分实验 | 实际结果/证据位置 | 状态 | 适用环境与版本 |
|---|---|---|---|---|

排除记录用于避免重复探索；版本、输入或条件改变后可以重新打开假设。问题暂时消失不等于修复。第一个原因成立后，仍从原入口检查是否存在叠加原因。

暂时无法完整复现时，继续读取相关代码、日志，缩小环境差异，或添加必要诊断。代码路径与定向失败测试可以证明局部缺陷，但不能冒充用户环境复现。用户明确要求“复现后才能修改”时，保持该执行边界。不要无限增加负载或扩大修改范围来强求复现。

## 最小修复与同法验证

只修改证据支持的原因，保留不相关的已有行为。独立旧问题记录为后续事项；本次引入的回归应修复。

修后重跑原入口、原关键条件及失败输入，不用更小数据、另一个入口或新配置代替原验收。增加与改动相关的相邻路径检查，例如恢复、取消、边界输入或配置覆盖；不默认全量扩展测试。

按待证明的边界选择测试：纯逻辑用确定性测试；超时/竞态可控制时钟或上游；真实 provider、系统或发布入口有实际变化时补对应真实验证。准确说明模拟测试与实际运行各自覆盖的范围。

断言用户可观察结果、持久化状态或真实产物，避免只检查 AI 回复里的“成功”。新增回归测试应能在旧行为或受控回归下失败。

## 交付

先说原流程是否恢复，再给：根因链、修改、修前/修后证据和未验证条件。明确区分实测确认、代码路径确认、推断及未复现。未运行的命令不能算验证。

如果复现消失但无因果证据，报告“本次未再复现，根因未确认”；如果仅局部回归通过，报告其范围。新证据推翻此前判断时明确更正。

复杂调查可按 [排障记录](assets/task-record.md) 保存复现、假设实验与同条件复测。

---
name: ajiang_contract_audit
description: 审计跨模块或跨系统集成的生产者与消费者契约，核验配置、身份、格式、状态、生命周期和错误传播，定位静默失败、配置未生效与兼容性问题。
license: MIT
---

# 跨系统契约检查

目标是证明当前集成产生的结果被真实消费者正确使用，失败和未知状态不会被伪装成成功。

## 确定真实链路

从用户动作或故障现象出发，追踪输入、配置解析、实际执行值、执行、持久化、后续读取与展示。读实际消费代码或运行时，不仅看类型、扩展点声明和写入函数。

记录版本、运行组合和目标平台。对插件或依赖升级，确认精确起止版本，读取两版实际接口、变更文档、依赖解析与最终消费者。项目已有迁移规则时遵循；没有时建立变更位置、目标行为、验证方法三列的迁移记录。不从历史案例推导当前 API。

## 在相关边界回答这些问题

按任务选择适用项，不把表格当成全仓检查要求。

| 契约维度 | 需要核验的差异 |
|---|---|
| 身份与基数 | 名称是否唯一；路径字符串是否代表同一对象；一条事件与一次任务是否对应；计量数据是否被重复计算 |
| 来源与优先级 | 权威目录与缓存/兜底谁优先；环境变量、配置和 UI 的值谁生效；版本是否匹配 |
| 状态语义 | 存在是否等于有效；未找到是否等于删除；未支持、失效、未启用和查询失败是否区分 |
| 格式与消费者 | 单位、schema、枚举、扩展字段及封装，在展示、恢复和迁移后是否仍能使用 |
| 能力与组合 | 当前运行时真正注册了哪些能力；可选能力缺失时是否可解释地降级；必需能力缺失是否明确失败 |
| 生命周期 | 冷启动、升级、恢复、取消、清理或重启后，状态与资源是否一致 |
| 错误与重试 | 异常是否进入可诊断渠道；结果未知时如何核对；成功操作是否又被重放；重复执行是否有副作用 |

对每个实际疑点记录生产者、消费者、约定、观察值、失效后果和证据。没有核实的契约差异保留为假设。

## 用反例验证

选取少量能暴露当前问题的坏状态，例如过期凭证、过期能力目录或缓存、可选工具缺失、迁移前后新增字段、查询失败、重复事件、取消后重试。不要只跑正常路径。

检查输出与状态，以及失败是否可见。一个“保护代码”只有在对应坏场景确实触发诊断或阻止错误结果时才有证据。数据库或历史迁移在隔离副本中验证。

缺失不自动等于删除；可能已执行的外部写入不自动重试。先查询真实结果，结合幂等性与当前授权选择恢复方案。授权范围以当前任务为准。

## 修复与验收

用户要求只检查时输出发现，不扩大成改造。已授权修复时优先修正权威来源、统一语义或补真实消费者支持；别为通过测试而放宽原有安全/完整性约束。

历史脏状态是否需要有界修复、后续写入是否还会产生同类问题、消费者是否仍可兼容，应按实际影响判断。自愈操作需要有依据且可观察，不覆盖任意未知状态。

复测从真实入口走到实际消费者。日志使用关联 ID 和脱敏配置身份，不泄露凭证。异步后台任务可以保持异步，但失败要有任务状态、可用诊断或适合该流程的错误呈现。

## 输出

交付相关契约表、已确认差异与后果、负向实验、修复及未覆盖版本/平台。区分成功、失败和结果未知；进程存活、类型通过或 UI 保存成功不单独证明整条链路成功。

跨多条接口或多个版本时，可按 [契约审计记录](assets/task-record.md) 保存契约差异、负向实验与结论。

---
name: ajiang_adversarial_review
description: 对软件变更进行独立审查，沿用户需求、实际入口与变更影响链寻找可复现缺陷，并逐条核验发现。用于独立审查、对抗审查或高影响变更的回归风险评估。
license: MIT
---

# 独立审查与证据裁决

目标是发现变更的真实缺陷，避免实现者自证，也避免照单全收审查者的推断。

## 给独立审查者的事实包

在当前宿主和任务授权允许委派时使用独立 agent。优先传递必要事实，避免继承实现者完整推理与“为什么肯定正确”的结论。

共同输入包括：目标仓库与工作区、项目规则、目标 SHA/diff、原任务、用户验收条件、必要原始复现材料及已运行检查的原始结果。如提供参考仓库，标明其只读性质。发现的问题不能由审查者直接混入主工作区。

审查者职责是只读审查与在隔离位置执行必要验证；报告给主审查者统一核验和裁决。明确允许写入的临时位置、可执行操作及结束条件，不让审查任务扩展成重做整个项目。

## 按失效方式分工

两路通常足以起步：一路检查原需求与用户实际入口，一路检查变更影响、错误/取消/恢复/资源清理。平台、协议或数据迁移有额外风险时再增加专门视角，不按固定人数重复检查。

独立审查不以“找满若干个 bug”为目标。可以报告没有发现已确认问题，同时说明查过哪些关键路径、哪些缺少证据。无需为了显得均衡机械地添加赞扬。

委派不可用或当前规则不允许时，用不同检查视角继续推进并说明限制；不能将单一 agent 的多轮思考报告成多个独立审查者。

## 发现协议

每条发现给出：

- 文件与位置、适用版本或 diff。
- 触发条件与用户可见后果。
- 生产者到消费者或调用路径。
- 实测证据、完整代码路径证据，或尚未补齐的证明。
- 与本次改动的关系：新增回归、阻断原目标的已有问题，或无关旧问题。

区分已确认、高度可疑与待确认，并注明是实测还是代码推导。理论上可能、风格偏好和实际 bug 分开；仅因“不喜欢写法”不能列为阻断项。

## 裁决与复核

逐条核验关键发现，记录采纳、驳回或待确认及理由。重复发现合并，多数票不能代替证据。仅要求审查时交付发现与裁决；已授权修复时，只修改已确认且与任务相关的问题。无关旧问题记录为后续。

修后运行对应失败实验与受影响验收；新回归需要处理。仅复核实际新变化和相关路径，不无条件重跑所有审查。范围或资源发生实质变化时，报告未解决项而非无限循环。

## 交付

先报告影响任务完成的有效发现，再给裁决、验证和未覆盖范围。没有已确认发现时也限定审查范围，不声称“保证无 bug”。

审查结论绑定具体版本。后续同步、合并、解决冲突造成的变化需要相应复核，不能把旧 SHA 的通过自动转移到新状态。

发现较多或需要多轮复核时，可按 [独立审查记录](assets/task-record.md) 保存证据、裁决和复核版本。

---
name: ajiang_ablation_refactor
description: 用单变量消融实验判断复杂机制应保留、删除、合并或替换，比较行为、失败防护与实际成本。用于简化代码、减少重复实现、降低成本或评估机制是否必要。
license: MIT
---

# 消融式重构

不要从“架构看起来乱”直接推导全面重写。用实验定位无收益的复杂度，同时保留有价值的保障。

## 定义需要保留的结果与基线

写清原用户任务、行为/数据契约与必须保留的失败防护。选择代表任务的正常路径及相关错误、恢复、边界或低频场景。

采集与当前问题有关的基线：耗时、模型调用/成本、内存、依赖、重复实现维护点、故障或误阻断。代码行数用于寻找候选，不独自作为质量指标。

## 找候选并单变量实验

优先查：同一规则的多份实现、同一数据的多份来源、昂贵复核层、保留的旧入口、没有实际消费者的配置、反复转换的数据、令真实测试无法覆盖的依赖关系。

在隔离工作副本或可回滚实验中，一次移除、绕开或替换一个机制，重跑同一输入与验收。记录实验改变了什么、哪些结果维持、哪些结果退化、成本如何变化。任务只要求评估时，实验不能变成对正式源码的永久重构。

安全、数据完整性与恢复护栏必须有对应失败或攻击场景。正常样本没有差异，不足以证明这些护栏冗余。难以观察收益的候选标成待验证，不凭名称删掉。

## 作出具体取舍

| 候选机制 | 原责任 | 实验变化 | 行为证据 | 成本变化 | 结论 |
|---|---|---|---|---|---|

结论可为保留、删除、合并、替换或待验证。合并重复实现前查平台、接口和行为差异；统一代码不能靠删掉必要差异实现。

选择能解决当前用户问题的最小组合，说明收益与迁移代价。不要把每个已有问题都纳入，也不要为了减少现有层数再引入一套没有被需要的新框架。

## 落地与退役

任务已经授权实施时继续完成具体改造；仅要求分析时交付可审查方案。修改触及正式数据/迁移或外部操作时遵循当前授权，不从“重构”推导额外权限。

新路径上线后检查旧函数、路由/注册、配置、测试、依赖与公开文档。没有消费者的旧路径按证据退役；兼容入口暂时保留时说明责任和可验证的退役条件，避免永久双轨。

重跑基线任务及相关回归，测量实际成本。必要的不变量由回归测试守住；不编写只匹配目录结构、命名或实现文本的测试。

## 交付

说明保留了什么用户结果、实验支持删掉什么、成本如何变化、旧路径是否退役。没有测量的收益不写为数字。一次任务成功不能宣称所有历史行为等价；未覆盖的平台与低频条件明确列出。

候选较多或需要多轮实验时，可按 [消融实验记录](assets/task-record.md) 保存基线、单变量变化、取舍和退役证据。

---
name: ajiang_newcomer_acceptance
description: 从干净配置和普通用户入口出发，仅按公开说明完成第一项真实成果。用于验收安装包、安装流程、README、首次运行入口或排查新用户上手阻塞。
license: MIT
---

# 新用户第一条成功路径验收

目标是证明首次使用者仅凭公开说明，能从普通安装入口获得第一项真实成果。

## 固定验收对象

确认待验收版本、安装渠道、目标平台、公开 README 和第一项成果。区分源代码开发环境与普通用户拿到的包/安装器。文档测试从其承诺的路径开始，发布包测试从真实产物开始。先按公开步骤执行；遇到阻塞后再读取源码定位原因，源码发现不能代替公开说明。

使用隔离目录、独立配置/profile 或适当的干净环境，保持用户已有配置不变。不复用开发环境中未在文档声明的配置、缓存或登录态。

交互路径使用用户指定或宿主要求的浏览器、桌面工具执行。无法操作目标界面时，标记该步骤未验证并交接具体人工动作；命令行检查只证明其实际覆盖的行为。

## 按公开步骤执行

逐项按文档执行，不自行补齐公开说明里遗漏的前置条件。遇到阻塞先记录位置、命令/动作、实际结果、对新手的影响及必要的缺失说明，再做任务范围内的修正。

外部账号、凭证或权限是明确前提时，验证文档是否说清获取与配置路径。缺少这些条件时标记对应阶段未验证，不虚构成功，不将用户已有登录态当成新用户验收。

从普通入口验证首次运行、依赖或资源获取、必要配置、执行目标任务及获取结果。安装/进程启动成功只是中间状态。

优先断言外部可见成果，例如文件存在且内容有效、工具真的改变指定对象、页面可访问、任务状态与结果一致；AI 回复中的“完成”不能单独通过验收。

## 修正后从公开路径复测

已授权修复文档或入口时，补齐实际阻塞并按修正后的公开步骤验证。复杂安装变化尽量在新的干净配置下复测，避免第一次运行的缓存或手工补丁让第二次看似成功。

不要反复运行已成功且有副作用的外部动作来获取更好看的日志。结果未知时先核对实际状态，按幂等性决定下一步。

## 交付与人工边界

交付版本/产物身份、所走的公开步骤、首项成果证据、已修卡点及未验证阶段。区分阻断、容易误导和可选改善，不因为能优化就扩大成重做整套 onboarding。

无法执行的桌面、硬件或系统授权步骤，提供环境要求、动作、预期结果、通过条件和问题记录，交接尚未验证的阶段。

验收涉及多个步骤时，可按 [新用户验收记录](assets/task-record.md) 保存公开路径、卡点、首项成果和人工交接。

---
name: ajiang_git_delivery
description: 提交已验证的代码改动、集成到指定目标分支或创建 PR。用于 commit、合并改动或交付 PR，检查提交范围、依赖、冲突语义与集成后的验证结果。
license: MIT
---

# 明确范围的提交与集成

## 固定源码与目标

读取项目 Git 规则，查看 status、当前分支/HEAD、暂存与未暂存差异、目标分支和 worktree 列表。区分本次改动与已有用户改动；不自动 reset、clean、stash 或覆盖不相关工作。

目标目录不是 Git 仓库时，报告无法完成提交的原因，不自行初始化仓库。用户仅要求本地提交时不扩展到 push/PR。

## 可单独评审的提交

只暂存已核实的任务文件；同文件混有无关修改时先分离可归属改动，无法安全分离的实质歧义交代清楚。独立根因尽量分提交，便于评审和回滚。提交信息写行为与原因，沿项目风格；仅真实存在的 issue 才写编号。

验证应对应将提交的内容。已有脏工作区上的一次通过不证明不相关文件缺席后也通过，需要时在隔离副本验证。

## 集成到最新目标

按当前授权更新目标信息；获取远程引用与集成本地工作区分开处理。检查目标是否被另一个 worktree 检出、是否有未提交改动。通过正常 Git 操作维护 HEAD 与工作区一致性，不能硬更新已检出目标的引用来绕过限制。

使用仓库既定合并策略。若要求“仅合本次提交”，先确认提交范围及其依赖；可 fast-forward 时使用 ff-only，否则只挑选已确定的本次提交。不要把此策略强加给所有仓库。

冲突先看两边业务语义和原验收，不选择看起来能编译的一边交差。有证据能确定的冲突可在已授权范围内解决；取舍无法从现有信息判断时留下具体冲突和选项，等待必要输入。

集成后查看目标差异，并验证合并/冲突影响的原任务和相邻路径。没有 Git 文本冲突不等于没有行为冲突。patch-id 仅帮助辨认补丁，不等同于完整目标树和运行环境相同。

## 外部交付

仅执行当前请求包含的 push 或创建 PR；清理分支或 worktree 时遵守项目约定及已有授权。本地提交成功、远程上传成功、CI 通过是不同状态。已授权 PR 时交付真实 URL；未创建不能编造。

PR 说明写实际问题、最终行为、必要验证与未覆盖项，省略讨论历史和没有实现的方案。收到 CI 失败时确认是否为本次相关问题，修复相关原因并观察新结果。输出提交/目标身份及实际完成的交付层。

跨多次提交或集成时，可按 [Git 交付记录](assets/task-record.md) 保存源/目标版本、提交范围、依赖与集成验证。

---
name: ajiang_release_verification
description: 准备指定版本的发布说明，核对版本、tag、CI 与实际产物身份，并从发布包或部署入口验证此次变化。用于发版、准备版本交付或验收已发布版本。
license: MIT
---

# 发布与产物自证

沿用项目现有发布流程，准备指定版本或验收已发布版本。

## 准备可评审结果

确认发布方式、目标平台/渠道、版本来源、当前提交、既有 workflow 和授权边界。读取本次实际 diff 后写简洁 notes；说明用户能观察到的变化，性能数字须有测量依据。

核对各处版本声明、tag、lockfile、notes 与产物名称。沿现有约定更新，不让 CI 临时猜版本。用户要求 notes 先审核时，先完成具体 notes 和可评审变更，再在指定发布步骤等待；已授权的普通动作不反复请求确认。

## 观察实际发布

本地相关检查通过后，执行当前授权的提交、tag、CI 或发布方式。观察对应版本的真实运行结果，区分成功、失败、取消、仍在运行及未触发。push 成功不能冒充发布成功。

失败时基于日志核验原因与残留状态。重跑有界且必须确认不会重复发布或覆盖错误版本；结果未知时先查询发布状态。不要以修流水线为名重建无关配置。

## 验收普通用户拿到的产物

获取当前授权渠道中的实际产物，记录其版本、源码身份、文件摘要或供应链元数据。核对目标平台与入口；不要只跑源码目录代替发布包。

按产物类型执行有关验收：

- CLI/包：在隔离目录安装或解包，运行真实 bin/导出接口，观察一项实际任务及退出状态。
- 桌面：能执行的平台覆盖安装、首次启动和此次变更路径；升级有变化时增加对应旧版本到新版本的状态保留。
- 服务/网站：核对实际部署身份，调用部署入口，验证此次变更结果与必要错误路径。

没有目标 OS、GUI、签名或真实服务资源时限定覆盖范围，提供准确人工动作和通过条件。摘要正确仅证明身份或完整性，不能替代功能验收。

## 交付

给版本、渠道/产物位置、对应验证，以及失败或未验证部分。只执行到本地构建时报告本地构建；实际发布已成功但目标平台未验收时分别说明。

维护有界恢复方式：哪些任务文件能回滚，哪些外部发布需要既定撤回/替代流程。不能承诺能撤销任意用户数据或第三方操作。

需要跨阶段跟踪时，可按 [版本发布记录](assets/task-record.md) 保存版本身份、发布运行与产物验收。