AI Engineering Skills

一套面向真实业务研发场景的 AI Agent Skills 工作流集合。

本项目不是为了让 AI 更快地生成代码，而是为了让 AI 在明确的工程边界内完成需求分析、项目理解、方案设计、代码实现、质量审查、测试验证、发布检查和交接沉淀。

项目定位

AI 编程真正的问题不是“不会写代码”，而是：

• 没有理解需求就开始写
• 没有熟悉旧项目就乱改
• 绕开已有架构重新造轮子
• 在坏代码上继续堆补丁
• 缺少测试、审查、发布和回滚意识
• 上下文无法在不同 AI、不同开发者之间传递

本项目通过一套可复用的 Skills，把 AI 从“代码生成器”约束成“工程协作者”。

核心原则

让 AI 在开发过程中始终遵守以下原则：

没有需求澄清，不写代码。
没有项目上下文，不写代码。
没有实现方案，不写代码。
没有审查方案，不写代码。
没有测试验证，不合并。
没有发布检查，不上线。

Skill 覆盖范围

本项目包含以下类型的 Skills：

1. 工程流程 Skills

用于控制完整研发流程：

• using-agent-skills
• interview-me
• idea-refine
• spec-driven-development
• planning-and-task-breakdown
• incremental-implementation
• test-driven-development
• source-driven-development
• doubt-driven-development
• debugging-and-error-recovery
• code-review-and-quality
• code-simplification
• git-workflow-and-versioning
• production-merge-gate
• security-and-hardening
• shipping-and-launch
• observability-and-instrumentation

2. 项目理解 Skills

用于帮助 AI 理解业务、旧项目和架构边界：

• domain-modeling
• context-engineering
• code-knowledge-graph
• codebase-design
• improve-codebase-architecture
• diagnosing-bugs
• handoff

3. 业务定制 Skills

面向 Java Spring Boot、前端项目、数据库、接口契约、财务支付业务等真实业务场景：

• backend-springboot-project-context
• frontend-project-context
• database-change-review
• api-contract
• finance-payment-business-rules

其中 database-change-review、api-contract、finance-payment-business-rules 当前都是 active skills。实际执行时必须先由 using-agent-skills 判断是否 active；如果命中尚未实现的 planned skill，按 ai-skills/skills/using-agent-skills/workflow/planned-skill-fallbacks.md 使用 active skills 兜底，不能假装 planned skill 已经执行。

4. 前端设计与浏览器 Skills

用于补齐视觉设计、外部 Figma 还原能力路由和可重复浏览器自动化：

• frontend-design：没有现成设计稿时，负责视觉方向、排版、色彩、布局和动效。它不替代组件状态、数据流、可访问性或测试。
• Figma-to-code：本仓库不再分发来源授权不足的实现 skill。仅当运行时已有授权明确的外部 Figma-to-code skill 时才加载；否则把能力缺失作为 blocker 返回，不能用 frontend-design 冒充。
• playwright-cli：执行可重复的浏览器操作、Playwright 测试、截图、trace、请求 mock 和测试生成。
• browser-testing-with-devtools：继续负责实时 DOM、console、network、性能和可访问性诊断。

路由由用户目标决定，而不是看到某个关键词就加载所有前端 skills。

以上清单中的仓库内 skill 名称只列 canonical active skills；外部能力、兼容 wrapper 与 planned skills 分开说明或登记。规范化状态、数量与调用方式以 ai-skills/SKILL_REGISTRY.md 为准，不能把 wrapper 或 planned capability 计作新的 active 能力。

适用场景

本项目适合以下研发场景：

• 从 0 到 1 开发新系统
• 参照旧系统重建新系统
• 在已有系统中开发新需求
• 审查 AI 生成的代码
• 排查线上问题
• 进行旧模块技术债体检
• 生成代码结构图、辅助定位入口、调用链和高耦合点
• 梳理前后端接口契约
• 审查数据库变更
• 发布前检查
• 沉淀跨会话交接文档

执行审计和 Eval

生产上不能只靠文本纪律。真实任务需要留下可检查证据：

• Risk Route
• Required skills（始终含 using-agent-skills）和需要监控的升级触发条件
• spec / acceptance criteria（Fast Path 可省略）
• plan（Fast Path 可省略）
• verification command/method、Execution: completed、positive result，以及 typed evidence（详细的 exit code 0，或报告目录内经 SHA-256 校验的 artifact）
• review 的终态 verdict、Blockers: none 和已解决 reason
• High-Risk 与当前 intent 对应的 production gate 终态 verdict 和 Blockers: none；production-final 适用时必须同时提供 Readiness: ready 以及可执行的 rollout 和 rollback；answer / diagnose 不要求 gate，plan 只要求 pre

阻塞报告可以记录无法验证的明确原因，但这不属于完成证据，也不能通过完成型 eval。

本仓库提供最小 eval 案例库和审计脚本：

ai-skills/scripts/audit-run.sh ai-skills/evals/cases/<case>.md <run-output.md>

被审计报告必须包含 ## Audit Case 和与案例文件名一致的 - ID: <case>，以及与案例 ## Task 一致的 - Task:；这能阻止拿无关 但格式相似的报告冒充该案例证据。Fast Path 仍需 verification 和 review conclusion，只省略 spec/plan。

案例库位于 ai-skills/evals/。所有 samples/*.md 都必须登记到 samples/MANIFEST.tsv，主验证器会执行清单中的每个正、负样本，并拒绝漏登记、 重复、缺失或预期结果漂移。每个负样本还必须登记它所针对的诊断子串；仅仅因为 另一个无关错误而退出非零不能让该样本通过回归。它先解决“有没有按流程执行”的 问题；后续真实生产样本应继续统计风险发现率、错误率、耗时和误阻塞率。

推荐工作流

所有任务先进入 using-agent-skills 的 risk-router：

• Fast Path：低风险小改动，允许最小流程
• Standard Path：普通需求，必须有 spec + plan + review
• High-Risk Path：资金、权限、数据库、状态、事务、发布、事故；当前 authoritative v1 按 intent 和制品生命周期执行对应的 production-merge-gate，只有 change 同时需要 pre 与 final

流程执行中发现风险升级条件，必须自动升级。High-Risk Path 不允许自动降级。

原生子代理编排与风险路由正交：两个或以上独立工作流应并行委派，只读探索和独立 审查优先；并行实现必须有稳定契约和互不重叠的写入所有权。以下流程图是条件能力 地图，不是每个任务都要串行执行的固定链。

Diff / PR 审查

Diff / PR
-> code-knowledge-graph review-impact（影响范围不清时，可选）
-> code-review-and-quality open-code-review runner（ocr 可用时，可选）
-> code-review-and-quality（汇总、复核、补充通用质量问题）
-> finance-payment-business-rules（涉及资金时）
-> database-change-review（涉及数据库时）
-> production-merge-gate（仅 High-Risk；声明可合并前的最终闸门）

code-review-graph 只提供影响范围证据，open-code-review 只提供行级候选问题。最终审查结论仍由现有 review / business / database / production gate skills 给出。

新需求开发

using-agent-skills
-> interview-me / domain-modeling（需求不清时）
-> domain-modeling（术语、角色、状态或业务规则不清时）
-> backend-springboot-project-context / frontend-project-context / context-engineering（按任务适用性）
-> code-knowledge-graph（需要结构图证据时，可选）
-> finance-payment-business-rules（资金、账务、商户隔离或财务报表时）
-> spec-driven-development
-> planning-and-task-breakdown
-> api-contract（涉及 API、导出格式、请求/响应字段或公开接口时）
-> database-change-review（涉及 schema、SQL、查询语义、索引、历史数据或兼容性时）
-> source-driven-development（框架、API 或平台行为需要官方依据时）
-> doubt-driven-development（Standard / High-Risk 的非平凡决策）
-> code-review-and-quality（非平凡方案的实现前审查）
-> production-merge-gate（高风险时作为实现前方案闸门）
-> incremental-implementation
-> test-driven-development
-> security-and-hardening / observability-and-instrumentation（按风险适用）
-> code-review-and-quality（实现审查）
-> shipping-and-launch（高风险时先准备 rollout/rollback，尚不部署）
-> production-merge-gate（高风险时作为实现后合并闸门）
-> Review Conclusion（最终闸门后形成唯一终态结论）
-> git-workflow-and-versioning（修改代码或使用 Git 时；分支/提交仍需授权）
-> handoff（需要跨会话时）

Figma 设计还原

用户提供 Figma URL，要求实现页面或组件
-> using-agent-skills
-> frontend-project-context
-> 运行时已安装且再分发/使用授权明确的外部 Figma-to-code skill；缺失则阻塞
-> spec-driven-development
-> planning-and-task-breakdown
-> source-driven-development（框架或 Figma 平台行为需要官方依据时）
-> doubt-driven-development
-> code-review-and-quality（方案审查）
-> incremental-implementation
-> test-driven-development
-> playwright-cli（需要可重复浏览器流程时）
-> browser-testing-with-devtools（需要运行时诊断时）
-> code-review-and-quality
-> git-workflow-and-versioning

如果用户要修改 Figma 画布，而不是实现应用代码，应改用可用的 Figma 画布 skill。任何外部 skill 都必须先确认当前运行时可用及其许可边界；仓库不得把未分发的名字写成无条件依赖。

无设计稿的前端视觉设计

用户要求从零设计或重塑页面视觉
-> using-agent-skills
-> frontend-project-context
-> frontend-design
-> spec-driven-development
-> planning-and-task-breakdown
-> doubt-driven-development
-> code-review-and-quality（方案审查）
-> incremental-implementation
-> test-driven-development
-> browser-testing-with-devtools
-> code-review-and-quality
-> git-workflow-and-versioning

普通行为型 UI 修改不自动加载 frontend-design。

浏览器自动化

用户要求自动完成登录、填写表单并验证结果
-> using-agent-skills
-> playwright-cli
-> spec-driven-development
-> planning-and-task-breakdown
-> doubt-driven-development
-> code-review-and-quality（方案审查）
-> incremental-implementation
-> test-driven-development
-> code-review-and-quality
-> git-workflow-and-versioning

需要检查 DOM、console、network、性能或可访问性时，再组合 browser-testing-with-devtools。

本地分发

先预览，再明确选择目标；脚本不会再默认写入所有全局 skill 目录。

# Agent Skills 标准目录：~/.agents/skills
bash ai-skills/scripts/link-skills.sh --target agents --dry-run
bash ai-skills/scripts/link-skills.sh --target agents

# 其他目标必须显式指定
bash ai-skills/scripts/link-skills.sh --target claude --dry-run
bash ai-skills/scripts/link-skills.sh --target claude
bash ai-skills/scripts/link-skills.sh --target codex --dry-run
bash ai-skills/scripts/link-skills.sh --target codex

第三方来源的离线基线验证包含在完整 validator 中。需要从官方固定提交重新 锚定许可证与导入文件时，运行：

bash ai-skills/scripts/verify-upstream-provenance.sh --online

使用 --target all 才会同时分发到所有支持的目标。脚本不会覆盖不由本仓库管理的 现有目录；如果目标经 canonical path 解析后相同、互为父子目录、符号链接别名或仅 大小写不同，也会在写入前拒绝，避免一个 harness 的结果覆盖另一个。

agents 和 claude 目标是指向本项目 skill 目录的受管 symlink，项目移动或删除后 链接会失效；codex 目标生成自包含 wrapper 副本。任何实际分发都会先执行 validate-skills.sh --source-only；验证器缺失、不可执行或验证失败时，在创建目标目录 之前终止。随后才进行完整冲突预检和 staging/backup 事务更新；发现用户自有冲突时 不会先改一半。

真实事务分发需要 Python 3，并仅支持 Darwin 和 Linux。Darwin 通过 renamex_np(RENAME_EXCL)、Linux 通过 renameat2(RENAME_NOREPLACE) 执行内核级原子排他 rename；不再使用存在 check-to-rename 竞争窗口的 mv -n。启动前检查只证明当前 libc 暴露相应 API， 具体目标文件系统不支持、跨文件系统、权限失败或 Linux 内核过旧仍会在真实 syscall 处失败，并由两端身份对账决定回滚或恢复。FreeBSD、NetBSD、OpenBSD 和其他未验证 平台会在任何目标变更前 fail closed。Python 以 -I -B 隔离模式运行，调用方的 PYTHONPATH、用户 site 和 bytecode 状态不能注入事务 helper。

事务不会递归删除非空的旧版本或中断时已生成的内容。成功替换、回滚冲突或恢复失败 时，脚本会在目标目录的父目录报告一个精确的 .ai-skills-recovery.<stage|backup>.* 兄弟目录；该目录位于 harness 的 skills/ 扫描根之外，也不会被后续运行自动清理。运维人员应先核对当前安装与报告的 recovery 内容，至少保留到回滚窗口结束；清理必须是另行授权的精确路径操作，不要对 .ai-skills-recovery.* 使用宽泛 glob 或递归删除。

Codex wrapper 安装到 ${CODEX_HOME:-~/.codex}/skills/<skill-name>。脚本不会在 Codex 保留的 .system 目录中新建本项目 skills；升级时只迁移或删除带本项目受管 marker 的旧 .system wrapper，不修改 Codex 自带或其他来源的内容。

外部引入或改编的 skill、固定审查版本和许可证清单见 ai-skills/THIRD_PARTY_SKILLS.md。 仓库级工作流文档和分发脚本的独立来源记录见 ai-skills/THIRD_PARTY_REPOSITORY.md。 根 LICENSE 当前不授予项目级开源许可；第三方许可证只覆盖各自明确 登记的来源材料，不会自动覆盖本仓库原创内容或本地修改。若项目所有者以后选择 MIT、Apache-2.0 或其他项目许可证，应显式替换根声明并继续保留第三方 carve-out。 已从工作树删除的受限 Figma 包仍存在于当前公开 Git 历史；在仓库所有者明确授权 并完成协同历史治理前，不能宣称该来源已从公共分发中清除。准备好的非执行性流程 见 ai-skills/docs/history-remediation.md。

Bug 排查

using-agent-skills
-> debugging-and-error-recovery / diagnosing-bugs
-> backend-springboot-project-context / frontend-project-context / context-engineering（按项目类型）
-> spec-driven-development / 压缩版验收标准
-> planning-and-task-breakdown
-> doubt-driven-development
-> code-review-and-quality（非平凡方案的实现前审查）
-> 风险复核：若触发 High-Risk，立即转入完整 High-Risk Path，
   并在任何代码修改前完成 production-merge-gate 方案闸门
-> incremental-implementation
-> test-driven-development
-> code-review-and-quality
-> production-merge-gate（仅上述 High-Risk 分支；验证后的最终合并闸门）
-> git-workflow-and-versioning（修改代码或使用 Git 时）

技术债治理

using-agent-skills
-> backend-springboot-project-context / frontend-project-context / context-engineering（按项目类型）
-> code-knowledge-graph（需要结构图证据时，可选）
-> codebase-design
-> spec-driven-development / 压缩版验收标准
-> planning-and-task-breakdown
-> doubt-driven-development
-> code-review-and-quality（方案审查）
-> production-merge-gate（触发 High-Risk 时，作为实现前方案闸门）
-> incremental-implementation
-> test-driven-development
-> code-review-and-quality
-> production-merge-gate（触发 High-Risk 时，作为实现后合并闸门）
-> git-workflow-and-versioning（修改代码或使用 Git 时）

improve-codebase-architecture 是 user-invoked skill；只有用户显式调用时， 才在 codebase-design 之后运行，不能把它作为自动路由依赖。

设计理念

本项目强调：

• 业务语言优先
• 调用链清晰
• 文件路径明确
• 小步实现
• 强制审查
• 测试验证
• 发布可回滚
• 上下文可交接
• 不确定点必须标注
• 禁止 AI 凭空猜业务规则

不是做什么

本项目不是：

• Prompt 大全
• 快速生成代码模板
• Vibe Coding 工具包
• 一次性项目脚手架
• 替代工程判断的自动化工具

它更像是一套研发纪律，把 AI 放进工程流程里，而不是让 AI 随意发挥。

一句话总结

让 AI 不只是会写代码，而是能在真实工程约束下参与软件交付。