structure｜1️⃣ 三级笔记、思想框架

核心主张

AI coding agents 默认走最短路径——跳过 spec、测试、安全审查。Agent Skills 把高级工程师的工作流编码为结构化 skill，让 agent 在开发全生命周期中保持生产级纪律。

Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development.

一、开发生命周期：6 阶段 × 7 命令

整个框架围绕软件开发的完整生命周期展开，用 7 个 slash command 作为入口：

• Define（/spec）→ 先写 spec，再写代码
• Plan（/plan）→ 把 spec 拆成小的、原子级任务
• Build（/build）→ 一次只做一个薄切片（thin vertical slice）
• Verify（/test）→ 测试是证明，不是装饰
• Review（/review）→ 合并前必须过质量门
• Ship（/ship）→ 越快越安全（Faster is Safer）

还有一个 /code-simplify 命令，核心原则是 clarity over cleverness。

Skills also activate automatically based on what you're doing — designing an API triggers api-and-interface-design, building UI triggers frontend-ui-engineering, and so on.

二、19 个核心 Skills：按阶段组织

Define — 搞清楚要建什么

• idea-refine：结构化的发散/收敛思维，把模糊想法变成具体提案
• spec-driven-development：在写任何代码之前，先写 PRD（目标、命令、结构、代码风格、测试、边界）

Plan — 拆解任务

• planning-and-task-breakdown：把 spec 分解为小的、可验证的任务，带验收标准和依赖排序

Build — 写代码

• incremental-implementation：薄垂直切片——实现、测试、验证、提交。Feature flags、安全默认值、可回滚
• context-engineering：在正确的时间给 agent 正确的信息——rules files、context packing、MCP 集成
• frontend-ui-engineering：组件架构、设计系统、状态管理、响应式设计、WCAG 2.1 AA 无障碍
• api-and-interface-design：契约优先设计、Hyrum's Law、One-Version Rule、错误语义、边界验证

Verify — 证明它能工作

• test-driven-development：Red-Green-Refactor、测试金字塔（80/15/5）、DAMP over DRY、Beyonce Rule
• browser-testing-with-devtools：用 Chrome DevTools MCP 获取实时运行时数据
• debugging-and-error-recovery：五步分诊法——复现、定位、缩小、修复、防护。Stop-the-line rule

Review — 合并前的质量门

• code-review-and-quality：五轴审查、变更大小 ~100 行、严重性标签（Nit/Optional/FYI）
• code-simplification：Chesterton's Fence、Rule of 500，在保持行为不变的前提下降低复杂度
• security-and-hardening：OWASP Top 10 预防、认证模式、密钥管理、依赖审计
• performance-optimization：先度量——Core Web Vitals 目标、profiling 工作流、bundle 分析

Ship — 部署上线

• git-workflow-and-versioning：Trunk-based 开发、原子提交、变更大小 ~100 行、commit-as-save-point
• ci-cd-and-automation：Shift Left、feature flags、质量门流水线、失败反馈回路
• deprecation-and-migration：代码即负债思维、强制 vs 建议废弃、迁移模式、僵尸代码清理
• documentation-and-adrs：ADR（架构决策记录）、API 文档、内联文档——记录 why
• shipping-and-launch：上线前检查清单、feature flag 生命周期、灰度发布、回滚程序

三、Agent Personas：预配置的专家角色

3 个预配置的 Agent 角色，用于针对性审查：

• code-reviewer：Senior Staff Engineer 视角，五轴代码审查，标准是「一个 staff engineer 会不会批准这个？」
• test-engineer：QA 专家视角，测试策略、覆盖率分析、Prove-It 模式
• security-auditor：安全工程师视角，漏洞检测、威胁建模、OWASP 评估

四、Skill 的统一结构（Skill Anatomy）

每个 skill 遵循一致的内部结构：

• Frontmatter：名称 + 触发条件描述
• Overview：做什么
• When to Use：什么时候触发
• Process：步骤式工作流
• Rationalizations：常见借口 + 反驳（反合理化表）
• Red Flags：出问题的信号
• Verification：证据要求

四个关键设计选择

1. Process, not prose：skill 是 agent 要执行的工作流，不是参考文档。每个都有步骤、检查点和退出标准
2. Anti-rationalization：每个 skill 都包含一张「常见借口表」，列出 agent 跳过步骤时会用的借口（如「我稍后再加测试」）以及对应的反驳
3. Verification is non-negotiable：每个 skill 结尾都有证据要求——测试通过、构建输出、运行时数据。「看起来对」永远不够
4. Progressive disclosure：SKILL.md 是入口，支持性参考资料按需加载，最小化 token 消耗

五、工程文化来源

技能中嵌入了 Google 工程文化的最佳实践：

• Software Engineering at Google + Google engineering practices guide
• Hyrum's Law → API 设计
• Beyonce Rule + 测试金字塔 → 测试
• 变更大小 ~100 行 + 审查速度规范 → 代码审查
• Chesterton's Fence → 代码简化
• Trunk-based development → Git 工作流
• Shift Left + feature flags → CI/CD
• 代码即负债 → 废弃策略

These aren't abstract principles — they're embedded directly into the step-by-step workflows agents follow.

六、适配多平台

• Claude Code（推荐）：plugin marketplace 安装
• Cursor：复制 SKILL.md 到 .cursor/rules/
• Windsurf：添加到 rules 配置
• GitHub Copilot：用 agents/ 定义 + .github/copilot-instructions.md
• Codex / Other Agents：纯 Markdown，任何接受 system prompt 的 agent 都能用

Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files.

concepts｜2️⃣ 关键概念、概念网络

一、核心概念解析 (Core Concepts)

• 【Agent Skills】(AI Agent 工程技能)

  • context：

    Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development.

  • 费曼一下：Agent Skills 是一套给 AI coding agent 用的「工程纪律包」。它把高级工程师的工作流程、质量门和最佳实践编码为结构化的 Markdown 文件，让 agent 像资深工程师一样在开发全流程中保持一致的专业标准，而不是走捷径。本质上是用 skill 的形式解决 agent 「默认走最短路径」的问题。

• 【Anti-rationalization】(反合理化)

  • context：

    Every skill includes a table of common excuses agents use to skip steps (e.g., "I'll add tests later") with documented counter-arguments.

  • 费曼一下：AI agent 和人一样会给自己找借口跳过关键步骤。Anti-rationalization 是一种预防机制：在每个 skill 中内置一张「常见借口表」，列出 agent 可能用来跳过步骤的典型借口，并配套对应的反驳论点。这是该项目最独特的设计之一——不只告诉 agent 「该做什么」，还预判它「会怎么逾」并堵死退路。

• 【Verification Gates】(验证门 / 质量门)
• 【Progressive Disclosure】(渐进式披露)
• 【Thin Vertical Slices】(薄垂直切片)
• 【Context Engineering】(上下文工程)
• 【Spec-Driven Development】(规格驱动开发)
• 【Hyrum's Law】(海勒姆定律)
• 【Beyonce Rule】(碟昆丝规则)
• 【Chesterton's Fence】(切斯特顿篡笆原则)
• 【Shift Left】(左移)

二、概念网络 (Concept Network)

• Agent Skills 是整个项目的顶层概念，它的核心设计由四个枱子支撑：Anti-rationalization（防偶工）、Verification Gates（防放水）、Progressive Disclosure（省 token）、Thin Vertical Slices（控风险）
• Spec-Driven Development → Context Engineering：spec 是给 agent 最重要的一份 context，spec 写得好，agent 执行质量才高
• Hyrum's Law → Verification Gates：因为任何可观测行为都会被依赖，所以 API 设计必须经过严格验证
• Beyonce Rule → Verification Gates：「在乎就写测试」是验证门的具体实践
• Chesterton's Fence → Anti-rationalization：防止 agent 以「简化」为借口删除不理解的代码
• Shift Left → Thin Vertical Slices：越早发现问题越好，而薄切片的循环方式让每一步都有及时反馈
• 所有工程文化概念（Hyrum's Law、Beyonce Rule、Chesterton's Fence、Shift Left）来自 Google 工程实践，被嵌入到具体的 skill 工作流中，从抽象原则变成了 agent 可执行的步骤

agentic reading｜3️⃣ 费曼 x3