jiawei/skills

Fork 0

Files

T

jiawei 69ecc1f6c4 feat: update README.md

2026-10-14 00:38:10 -07:00

11 KiB

Raw Permalink Blame History

Agent Skills

把可靠的工程方法沉淀为可复用的 Agent Skills。

本仓库收录符合 Agent Skills 规范的技能。每个 Skill 独立存放，包含供 Agent 执行的 SKILL.md，以及按需加载的参考资料；仓库另外提供模板、结构检查脚本和可复现的验证案例。

Skills

Skill	版本	解决的问题
bugfix	1.0.0	引导编程 Agent 证明 Bug 根因，识别同一缺陷机制的其他实例，从源头修复，并验证防复发检查是否有效。

bugfix：修复一类缺陷，而不只是一处报错

Fix the class, not just the instance.

AI 编程 Agent 往往能快速处理被报告的错误，但“当前场景不再报错”不等于问题已经解决。一个 Bug 可能只是共享错误假设的其中一处表现：相同的缺陷可能出现在旧版实现、其他调用方、不同语法写法中，甚至已经影响缓存、队列或业务数据。

bugfix 的目标不是让每次修复都扩大成项目重构，而是让 Agent 回答四个问题：

为什么会错？ 用可复现、因果、可逆和机制性证据确认根因，而不满足于“异常消失”。
还有哪里会错？ 定义缺陷类别，再沿复制代码、共享契约、错误假设、历史实现和已写入数据等方向查找同源实例。
应该在哪里修？ 优先消除错误机制；只有共享契约确实一致时才抽取公共修复，否则在已确认的位置进行协调修复。
如何防止再犯？ 用实际验证过的测试或检查阻止新的同类错误，并确认真实执行路径已使用修复后的代码。

核心能力

能力	具体做法
根因证明	以复现、因果验证、可逆验证和代码机制说明四项证据约束结论。
同源缺陷搜索	不只搜索同一段代码，还检查不同写法、相同契约的读写端、平行路径和受影响数据。
候选项判定	每个搜索结果都要标为已确认、已排除或待确认；不能把“看起来相似”直接当成 Bug。
按风险分级	Quick / Standard / Full 三种调查深度；遇到共享契约、安全、数据损坏等风险时升级。
防复发守卫	要求证明守卫能够拦住新的同类实例，而不是仅确认已有回归测试通过。
运行时与回归验证	对比修改前后的测试基线，核实真实入口与实际运行的产物；无法验证时明确说明。
安全边界	重大契约变化、依赖、数据修复、共享环境操作和部署等事项需要先获得授权。

调查流程

                      ┌─ Quick ──────────────┐
Phase 0  风险分级 ─────┤                      ├─ 修复与验证 → 报告
                      └─ Standard / Full ────┘
                               │
                 复现问题 → 根因证明
                               │
                 定义缺陷类别 → 同源实例清单
                               │
                 影响范围评估 → 从源头修复
                               │
                 守卫验收 → 回归及运行时验证
                               │
                         结果与遗留风险报告

Quick：明显、局部、低风险的问题。仍需精简的复现和因果证据，以及一次同类问题检查。
Standard：局限在少量文件、未涉及共享契约的普通逻辑缺陷。
Full：安全、数据损坏、共享代码或契约、并发、跨进程等高风险问题；执行更完整的范围分析与验证。

调查深度根据证据动态升级。这不是要求所有简单问题都进行全项目扫描，也不是要求每次修复都引入新抽象。

一个简化示例

报告的问题：商品搜索标签 art 时，错误返回包含 cart 的商品。

只修当前报错：将新版本搜索接口的子串判断改为精确标签匹配，然后结束。
根因导向的调查：确认错误来自“把子串包含误当成标签成员关系”；继续查找旧版搜索、正则匹配以及权限判定等是否存在同一错误假设；区分真正受影响的位置与合法的集合成员查询；再完成针对性修复和验证。

这个案例来自仓库的 inventory 验证夹具。它体现的是同一错误机制可能有不同代码写法和更高的安全影响，而不是“发现相似代码就全部修改”。

安装

只需安装 bugfix/ 目录（包括 SKILL.md 和完整的 references/）；tests/、scripts/ 和 templates/ 是仓库开发与验证工具，不需要复制到 Agent 的 Skill 目录。

作为 Claude Code 插件安装（仓库已包含 .claude-plugin/）：

/plugin marketplace add https://git.qflink.xyz/jiawei/skills.git
/plugin install marcus-skills@marcus-skills

安装后技能以插件命名空间调用，例如 /marcus-skills:bugfix。

使用

安装后直接描述需要修复的 Bug，Agent 可以根据 SKILL.md 的 description 判断是否启用；也可以显式调用。

Claude Code：

/bugfix 修复用户刷新页面后登录状态丢失的问题

Codex：

$bugfix 排查这个接口为何间歇性返回错误数据，并检查是否存在同源问题

自然语言：

修复订单状态偶发回退的问题。请先找到根因，再确认其他路径是否存在相同的错误机制。

适用于真实的 Bug、异常、错误结果、回归、间歇性故障及因缺陷导致的性能问题；不用于新功能开发、纯代码评审或不存在已知缺陷的普通性能调优。Skill 的自动触发由 Agent 判断，不保证每次描述 Bug 都会自动启用。

结果报告

Skill 要求最终明确归入以下四种状态之一，避免用笼统的“已修复”掩盖证据缺口：

状态	含义
未修复	原始问题尚未得到代码层面的修复及验证。
部分修复	仍有已确认或未解决的同类实例。
本地已修复，线上未验证	代码与检查已通过，但执行中的实际产物尚未核实，或部署、重启待授权。
整类缺陷已修复	已确认的实例、守卫验收及实际运行验证均完成，达到 Skill 定义的完成条件。

当运行环境没有浏览器、服务访问或测试执行能力时，Agent 应报告验证限制，而不是声称已经验证。

验证与测试

仓库提供的验证设施不只是检查 SKILL.md 是否符合格式，还包括对 Agent 行为的盲测。

规范与链接检查

从仓库根目录执行：

python scripts/check_skills.py
# 只检查 bugfix
python scripts/check_skills.py bugfix

该脚本检查 frontmatter、名称、描述和 Markdown 相对链接，并对正文长度提供提示。完整的 Agent Skills 规范验证可另行使用官方参考校验器。

盲测案例

案例	仅报告的症状	主要考察
`inventory`	标签搜索发生错误匹配	不同写法的同源问题、权限影响、缓存错误和正确代码的排除。
`scheduler`	重试延迟比配置短得多	秒/毫秒契约不一致、相关调用端、队列中已写入的错误记录。

仓库的 RESULTS.md 记录了 2026-10-13 的两次 Codex CLI 内部盲测：上述两个案例均按预先编写的评分标准得到 18/18。同时记录了因测试暴露的问题而修改 Skill 的过程，以及守卫回退配方的安全回归检查。

注意：这只是两个受控夹具的测试记录，不能据此推断真实工程中的普遍修复成功率、可靠性提升幅度或跨模型泛化能力。完整的运行方法、评分方式及安全前提参见 tests/bugfix/README.md。

在 Linux、macOS 或 Windows Git Bash 环境中，可从仓库根目录准备盲测夹具：

bash tests/bugfix/setup_fixture.sh scheduler /tmp/bf-scheduler > /tmp/bf-scheduler.prompt.md

再将生成的提示词交给被测 Agent，在夹具仓库中执行并根据独立的 rubrics/ 评分。测试时应核查实际代码差异与运行结果，而不仅仅阅读 Agent 的文字报告。

仓库结构

.
├── .claude-plugin/                  # Claude Code 插件清单与 marketplace
├── bugfix/
│   ├── SKILL.md                     # 技能入口、分级流程、执行规则
│   └── references/                  # 按阶段加载的分析与验证材料
│       ├── root-cause.md            # 根因分析
│       ├── class-analysis.md        # 同源缺陷搜索与守卫验收
│       ├── system-rca.md            # 跨组件、跨进程问题
│       ├── bug-patterns.md          # 常见缺陷模式
│       ├── frontend-patterns.md     # 前端故障模式
│       ├── backend-patterns.md      # 后端故障模式
│       ├── blind-spots.md           # 影响范围中的常见盲区
│       ├── verification.md          # 基线、回归及运行时验证
│       └── project-knowledge.md     # 项目知识的使用与维护
├── tests/bugfix/                    # 夹具、提示词、评分标准、验证记录
├── scripts/check_skills.py         # Skill 结构检查
├── templates/skill-template/       # 新 Skill 模板
└── README.md

设计边界

不替代 Agent 的判断：规则提供调查框架，但结论仍需事实与实验支撑。
不默认进行全仓库重构：先定义缺陷类别，再根据证据确定搜索与修改范围。
不把搜索命中视作缺陷：必须有失败样例或可追踪的不变量违例，才确认同源实例。
不擅自进行高风险操作：公共契约变更、新依赖、权威数据修复、共享服务操作及部署等需征得用户同意。
不伪造完成状态：无法运行的测试、未验证的线上版本和未处理的数据必须明确列出。

11 KiB Raw Permalink Blame History Unescape Escape