AI Playbook：AI 辅助开发的标准化规则与多智能体工作流

AI Playbook 是一个用于标准化 AI 助手代码贡献的共享规则库，通过可复用的规则文件、结构化命令、智能体技能和多智能体配置，实现跨项目的一致、安全、可审计的 AI 辅助开发。

AI 辅助开发的挑战\n\n随着 Cursor、Claude Code 等 AI 编程助手的普及，开发团队面临一个新的挑战：如何在不同项目中保持 AI 行为的一致性。复制粘贴 AI 规则不仅难以扩展，还会导致静默的行为漂移、不一致的安全保证和不受控制的 AI 变更。每个项目可能有不同的代码风格、安全要求和分支策略，如果没有统一的规范，AI 助手的行为将变得不可预测。AI Playbook 项目正是为解决这一问题而生，它提供了一个可复用的 AI 行为基线，作为跨项目的单一事实来源。\n\n## 项目定位\n\nAI Playbook 是一个工具无关的基础规则库，其规则、命令和技能适用于 Claude Code 和 Cursor。多智能体配置主要针对 Claude Code，但基础功能在所有支持的工具上都能工作。项目强调安全优先和面向生产环境，确保 AI 辅助开发既一致又安全。\n\n值得注意的是，AI Playbook 不是项目特定的文档、应用程序代码或框架/SDK，而是一个可重用的 AI 行为基线。它通过 Git 子模块或符号链接包含在项目中，每个项目可以固定特定版本并有意识地升级。\n\n## 核心组件架构\n\n### 可复用规则（.mdc）\n\n规则文件定义了 AI 的持久性行为约束。这些规则确保 AI 在不同项目中遵循一致的代码风格、安全策略和最佳实践。通过将规则集中管理，团队可以避免在每个项目中重复定义相同的行为规范。\n\n### 结构化命令\n\n项目提供了一系列斜杠触发的结构化命令，包括 /start、/feature、/fix、/refactor 等。每个命令都遵循完整的工作流：分支创建、实现、验证、文档更新和提交推送。这种标准化的命令体系确保了 AI 助手的每次交互都有明确的意图和可预测的结果。\n\n### 智能体技能（.agents/skills/）\n\n技能是按需调用的领域专业知识模块，如安全审查、约定式提交、发布说明生成等。技能不是由用户直接调用，而是由 AI 在检测到匹配任务时自动加载，或由命令引用时触发。这种设计实现了功能模块化，同时保持了使用的简洁性。\n\n### 多智能体配置（.agents/setups/）\n\n项目提供了多种预配置的智能体团队，适用于不同的开发场景。dev-squad-v2 适合 TypeScript/React TDD 开发，包含 3 个智能体（技术负责人 + 2 名高级开发）；pm-ba-squad-v2 专注于需求规格和用户故事；legacy-agents-v1 包含 14 个智能体的完整团队，用于遗留代码现代化；web2-agents-v1 提供 13 个智能体的全栈 SaaS 开发团队；web3-agents-v3 则针对智能合约和 DeFi 应用提供 10 个智能体。\n\n## 安全优先设计\n\nAI Playbook 将安全置于首位，包含 MCP 验证、后门预防和供应链感知等策略。项目遵循"安全 > 正确性 > 性能 > 便利性"的优先级原则，强调显式意图优于隐式行为，最小化魔法、最大化可审计性。AI 应该表现得像一名高级工程师，而不是自动补全引擎。\n\n## 安装与使用\n\n安装过程非常简单，只需 30 秒。首先克隆 playbook 仓库，然后选择适合项目类型的配置并运行安装脚本：\n\nbash\ngit clone https://github.com/KaelSensei/ai-playbook.git .ai-playbook\nbash .ai-playbook/.agents/setups/dev-squad-v2/install.sh\n\n\n安装后，在 Claude Code 或 Cursor 中打开项目并输入 /start，AI 就会加载项目文档、规则和进度跟踪，然后选择下一个任务并开始工作。\n\n## 命令详解\n\n### 工作流命令\n\n/start 用于每个新会话的开始，AI 加载项目文档、规则和进度跟踪，然后选择下一个任务并开始工作。/feature 用于添加新功能，/fix 用于修复问题，/refactor 用于代码重构。每个命令都会自动处理分支创建、实现、验证、文档更新和提交推送。\n\n### Git 工作流命令\n\n/git 命令自动执行暂存、提交和推送，自动生成提交消息。/create-branch 提供交互式分支创建，/create-pr 用于从当前分支向目标分支创建 PR，/merge-branch-into-main 执行带有安全审查的安全合并，/release 生成发布说明和 GitHub 发布。\n\n### 维护命令\n\n/audit-code 执行代码质量和安全审查，/magic-wand 进行深度根因分析，/cleanup-repo 重新组织分散的文件，/clean-code 移除死代码和冗余代码。/continue 命令让 AI 重新加载进度、检查当前分支并继续之前的工作。\n\n## 工具兼容性\n\n多智能体配置主要针对 Claude Code 作为首选工具。在 Cursor 上，命令和技能仍然有效，但子智能体角色会折叠为一个，且任何 shell 钩子（legacy-agents-v1、web2-agents-v1、web3-agents-v3 中的 guardrails）会被静默禁用，因为 Cursor 没有钩子系统。项目提供了详细的兼容性文档，帮助用户在选择配置前了解各功能的真实支持情况。\n\n## 版本与分支管理\n\nAI Playbook 强调版本和分支纪律。每个项目可以固定特定版本的 playbook，升级是有意识的决策。配置独立于应用程序代码，可以独立更新。这种设计确保了 AI 行为的稳定性，同时允许在需要时引入改进。\n\n## 总结\n\nAI Playbook 代表了 AI 辅助开发从"即兴发挥"向"工程化实践"的转变。通过标准化的规则、结构化的命令和多智能体配置，它为团队提供了一种可扩展、可维护的 AI 协作模式。随着 AI 编程助手的普及，类似的 playbook 和最佳实践将在软件开发领域变得越来越重要。

AI 辅助开发的挑战\n\n随着 Cursor、Claude Code 等 AI 编程助手的普及，开发团队面临一个新的挑战：如何在不同项目中保持 AI 行为的一致性。复制粘贴 AI 规则不仅难以扩展，还会导致静默的行为漂移、不一致的安全保证和不受控制的 AI 变更。每个项目可能有不同的代码风格、安全要求和分支策略，如果没有统一的规范，AI 助手的行为将变得不可预测。AI Playbook 项目正是为解决这一问题而生，它提供了一个可复用的 AI 行为基线，作为跨项目的单一事实来源。\n\n项目定位\n\nAI Playbook 是一个工具无关的基础规则库，其规则、命令和技能适用于 Claude Code 和 Cursor。多智能体配置主要针对 Claude Code，但基础功能在所有支持的工具上都能工作。项目强调安全优先和面向生产环境，确保 AI 辅助开发既一致又安全。\n\n值得注意的是，AI Playbook 不是项目特定的文档、应用程序代码或框架/SDK，而是一个可重用的 AI 行为基线。它通过 Git 子模块或符号链接包含在项目中，每个项目可以固定特定版本并有意识地升级。\n\n核心组件架构\n\n可复用规则（.mdc）\n\n规则文件定义了 AI 的持久性行为约束。这些规则确保 AI 在不同项目中遵循一致的代码风格、安全策略和最佳实践。通过将规则集中管理，团队可以避免在每个项目中重复定义相同的行为规范。\n\n结构化命令\n\n项目提供了一系列斜杠触发的结构化命令，包括 /start、/feature、/fix、/refactor 等。每个命令都遵循完整的工作流：分支创建、实现、验证、文档更新和提交推送。这种标准化的命令体系确保了 AI 助手的每次交互都有明确的意图和可预测的结果。\n\n智能体技能（.agents/skills/）\n\n技能是按需调用的领域专业知识模块，如安全审查、约定式提交、发布说明生成等。技能不是由用户直接调用，而是由 AI 在检测到匹配任务时自动加载，或由命令引用时触发。这种设计实现了功能模块化，同时保持了使用的简洁性。\n\n多智能体配置（.agents/setups/）\n\n项目提供了多种预配置的智能体团队，适用于不同的开发场景。dev-squad-v2 适合 TypeScript/React TDD 开发，包含 3 个智能体（技术负责人 + 2 名高级开发）；pm-ba-squad-v2 专注于需求规格和用户故事；legacy-agents-v1 包含 14 个智能体的完整团队，用于遗留代码现代化；web2-agents-v1 提供 13 个智能体的全栈 SaaS 开发团队；web3-agents-v3 则针对智能合约和 DeFi 应用提供 10 个智能体。\n\n安全优先设计\n\nAI Playbook 将安全置于首位，包含 MCP 验证、后门预防和供应链感知等策略。项目遵循"安全 > 正确性 > 性能 > 便利性"的优先级原则，强调显式意图优于隐式行为，最小化魔法、最大化可审计性。AI 应该表现得像一名高级工程师，而不是自动补全引擎。\n\n安装与使用\n\n安装过程非常简单，只需 30 秒。首先克隆 playbook 仓库，然后选择适合项目类型的配置并运行安装脚本：\n\nbash\ngit clone https://github.com/KaelSensei/ai-playbook.git .ai-playbook\nbash .ai-playbook/.agents/setups/dev-squad-v2/install.sh\n\n\n安装后，在 Claude Code 或 Cursor 中打开项目并输入 /start，AI 就会加载项目文档、规则和进度跟踪，然后选择下一个任务并开始工作。\n\n命令详解\n\n工作流命令\n\n/start 用于每个新会话的开始，AI 加载项目文档、规则和进度跟踪，然后选择下一个任务并开始工作。/feature 用于添加新功能，/fix 用于修复问题，/refactor 用于代码重构。每个命令都会自动处理分支创建、实现、验证、文档更新和提交推送。\n\nGit 工作流命令\n\n/git 命令自动执行暂存、提交和推送，自动生成提交消息。/create-branch 提供交互式分支创建，/create-pr 用于从当前分支向目标分支创建 PR，/merge-branch-into-main 执行带有安全审查的安全合并，/release 生成发布说明和 GitHub 发布。\n\n维护命令\n\n/audit-code 执行代码质量和安全审查，/magic-wand 进行深度根因分析，/cleanup-repo 重新组织分散的文件，/clean-code 移除死代码和冗余代码。/continue 命令让 AI 重新加载进度、检查当前分支并继续之前的工作。\n\n工具兼容性\n\n多智能体配置主要针对 Claude Code 作为首选工具。在 Cursor 上，命令和技能仍然有效，但子智能体角色会折叠为一个，且任何 shell 钩子（legacy-agents-v1、web2-agents-v1、web3-agents-v3 中的 guardrails）会被静默禁用，因为 Cursor 没有钩子系统。项目提供了详细的兼容性文档，帮助用户在选择配置前了解各功能的真实支持情况。\n\n版本与分支管理\n\nAI Playbook 强调版本和分支纪律。每个项目可以固定特定版本的 playbook，升级是有意识的决策。配置独立于应用程序代码，可以独立更新。这种设计确保了 AI 行为的稳定性，同时允许在需要时引入改进。\n\n总结\n\nAI Playbook 代表了 AI 辅助开发从"即兴发挥"向"工程化实践"的转变。通过标准化的规则、结构化的命令和多智能体配置，它为团队提供了一种可扩展、可维护的 AI 协作模式。随着 AI 编程助手的普及，类似的 playbook 和最佳实践将在软件开发领域变得越来越重要。