Playbooks 系统

注意： 本页描述了我们 Constitutional Engineering 理念的技术实现。如果您还没有阅读关于理念基础的内容，我们建议从那里开始，以理解 playbooks 背后的"为什么"。

Playbooks 系统是 Hatcher 针对 AI 开发中上下文问题的第二代解决方案。虽然像 Claude.md 这样的静态文件提供了一个起点，但 Playbooks 提供了一个动态的、集中的、可治理的系统，充当 AI 代理的真正企业宪章。

什么是 Playbooks？

Playbooks 是结构化的配置文件，捕获您团队的：

• 编码标准：格式化、命名约定和风格偏好
• 架构决策：组件模式、状态管理方法
• 框架细节：特定库的最佳实践和模式
• 业务规则：特定领域的逻辑和约束

Playbook 结构

一个基本的 Playbook 遵循以下结构：

{
  "name": "Vue 3 Component Standards",
  "version": "1.0.0",
  "framework": "vue",
  "rules": [
    {
      "category": "components",
      "type": "naming",
      "pattern": "PascalCase",
      "description": "All Vue components must use PascalCase naming"
    },
    {
      "category": "composition",
      "type": "api",
      "preference": "composition-api",
      "description": "Prefer Composition API over Options API"
    }
  ],
  "examples": [
    {
      "title": "Standard Component Structure",
      "code": "..."
    }
  ]
}

内置 Playbooks

Hatcher 附带了为流行框架精心策划的 Playbooks：

Vue.js Playbooks

• Vue 3 + TypeScript：现代组合模式
• Nuxt.js：SSR 和基于文件的路由约定
• Pinia：状态管理最佳实践

React Playbooks

• React + TypeScript：函数组件和 hooks
• Next.js：App Router 和服务器组件
• Zustand：轻量级状态管理

通用 Playbooks

• TypeScript Standards：类型定义和泛型
• CSS-in-JS：Styled-components 和 emotion 模式
• Testing：Jest 和 Cypress 约定

创建自定义 Playbooks

团队特定规则

创建捕获您团队独特约定的 Playbooks：

{
  "name": "Acme Corp Standards",
  "extends": ["vue3-typescript"],
  "rules": [
    {
      "category": "api",
      "type": "structure",
      "pattern": "services/api/*.service.ts",
      "description": "All API calls must go through service layer"
    },
    {
      "category": "components",
      "type": "props",
      "requirement": "interfaces",
      "description": "Component props must use TypeScript interfaces"
    }
  ]
}

项目特定上下文

添加项目特定知识：

{
  "name": "E-commerce Dashboard",
  "extends": ["acme-corp-standards"],
  "context": {
    "domain": "e-commerce",
    "entities": ["Product", "Order", "Customer"],
    "apis": [
      {
        "name": "OrdersAPI",
        "baseUrl": "/api/orders",
        "methods": ["GET", "POST", "PUT", "DELETE"]
      }
    ]
  }
}

Playbook 继承

Playbooks 支持继承以实现可扩展的配置：

Universal TypeScript
    ↓
Vue 3 + TypeScript
    ↓
Acme Corp Standards
    ↓
Project-Specific Rules

AI 集成

Hatcher 自动将相关的 Playbook 上下文注入 AI 提示中：

上下文选择

• 自动：基于文件类型和项目结构
• 手动：明确指定要使用哪些 Playbooks
• 智能：随着时间的推移从您的偏好中学习

提示增强

AI 引擎接收结构化的上下文，如：

CONTEXT: Vue 3 Component Creation
PLAYBOOK: vue3-typescript, acme-corp-standards
RULES:
- Use Composition API with <script setup>
- Props must use TypeScript interfaces
- Components must be PascalCase
- API calls go through service layer

市场与共享

社区 Playbooks

浏览并安装由社区创建的 Playbooks：

• 框架特定：为流行库优化的模式
• 行业特定：不同行业的领域知识
• 团队测试：来自成功项目的真实世界约定

发布您的 Playbooks

分享您团队的专业知识：

hatcher playbook publish acme-corp-standards

版本管理

• 语义化版本控制：跟踪更改和兼容性
• 更新通知：与社区改进保持同步
• 回滚支持：安全地还原有问题的更新

配置

全局 Playbooks

为所有项目设置默认 Playbooks：

{
  "globalPlaybooks": ["typescript-standards", "git-conventions"]
}

项目覆盖

在 hatcher.config.json 中指定项目特定的 Playbooks：

{
  "playbooks": ["vue3-typescript", "team-standards", "./custom-playbook.json"]
}

条件加载

基于上下文加载不同的 Playbooks：

{
  "conditional": {
    "**/*.test.ts": ["testing-standards"],
    "src/components/**": ["component-standards"],
    "src/api/**": ["api-standards"]
  }
}

最佳实践

从简单开始

从框架基础开始，逐步添加团队特定规则：

1. 安装框架 Playbook：立即获得 80% 的覆盖率
2. 添加团队规则：捕获独特的约定
3. 随时间优化：根据实际使用更新

保持更新

• 定期审查：随着模式演变更新 Playbooks
• 团队反馈：让整个团队参与 Playbook 维护
• 版本控制：与代码一起跟踪 Playbook 更改

衡量影响

• 一致性指标：跟踪对已定义模式的遵循情况
• 速度提升：测量开发速度增益
• 质量指标：监控代码审查反馈的减少

未来功能

AI 生成的 Playbooks

通过分析现有代码库自动生成 Playbooks。

实时验证

在您编码时提供实时反馈，确保符合 Playbook 规范。

团队协作

Playbook 更新的协作编辑和审批工作流程。

Playbooks 系统将 AI 从一个通用的代码生成器转变为一个理解您的确切要求和约定的专业团队成员。

创建您的第一个 Playbook

将 AI 转变为遵循您确切标准的专业团队成员

开始构建 Playbooks→

您的模式。您的标准。始终如一地应用。