1. 项目概述一个为工程团队设计的AI智能体技能与规则库如果你和我一样每天都在和Claude Code、Cursor这类AI编程助手打交道那你一定也经历过这种循环每次开启一个新会话都要重新描述一遍你的代码审查标准、项目架构偏好或者手把手教AI如何执行一个多步骤的自动化任务。这不仅浪费时间更致命的是输出的质量会随着你的耐心和描述的详细程度而波动。goodai-base这个项目就是为了终结这种低效循环而生的。简单来说goodai-base是一个精心编排的AI智能体技能与规则知识库。它不是一个简单的提示词合集而是一套完整的“操作系统”旨在将你的AI助手从一个需要反复调教的实习生转变为一个理解你团队规范、能自主执行复杂工作流的资深协作者。它的核心思想是“定义一次处处生效”你将团队的最佳实践封装成可复用的技能和规则然后一键同步到你日常使用的所有AI工具如Claude Code、Cursor、Codex等中。从此无论是进行深度代码审查、自动生成项目文档还是拆解一个复杂的GitHub Issue你只需要输入一个简单的命令AI就能基于预设的、高质量的工作流给出稳定、可靠的输出。这个项目特别适合那些已经将AI深度融入日常开发流程但苦于提示词管理混乱、输出不一致的工程团队和个人开发者。它通过结构化的方式将零散的“魔法咒语”变成了可维护、可扩展的工程资产。2. 核心设计理念从临时提示到工程化智能体在深入细节之前理解goodai-base背后的设计哲学至关重要。它解决的不是“如何让AI写代码”的问题而是“如何让AI像你的资深队友一样稳定、可靠地工作”。2.1 技能与规则的分离动态加载与精准匹配大多数人在使用AI助手时习惯将所有要求和偏好塞进一个冗长的“系统提示”或全局指令中。这带来了两个问题上下文污染和性能浪费。AI的上下文窗口是宝贵的无关的规则会挤占理解当前任务所需的空间同时让AI在每次交互中都“记住”所有规则也会增加不必要的计算开销。goodai-base采用了更精巧的“路由按需加载”模型技能这是可执行的、多步骤的工作流。例如/review-orchestrator是一个技能它接收到代码审查请求后会像项目经理一样自动调度12个不同专长的子智能体逻辑、架构、安全等并行工作最后汇总成一份报告。技能是“做什么”和“怎么做”的封装。规则这是静态的参考标准和规范。例如code-style-patterns.mdc文件里定义了你的TypeScript/React编码风格。规则是“按什么标准做”的参照。AGENTS.md这是整个系统的“路由表”和“总控大脑”。它本身并不包含具体的技能或规则内容而是一套逻辑判断指令。当AI读取到用户请求时会首先咨询AGENTS.md。AGENTS.md会判断“这个请求是关于代码审查的应该调用review-orchestrator技能并且在执行过程中如果需要检查代码风格再去动态加载rules/core/code-style-patterns.mdc文件。”这种设计带来了几个显著优势上下文清洁AI的工作记忆里只保留与当前任务最相关的指令思考更聚焦输出质量更高。灵活组合规则可以被多个技能复用。前端审查和后端实现技能都可以调用同一套代码风格规则保证了全栈的一致性。易于维护更新一个规则文件所有引用它的技能都会自动生效无需逐个修改技能定义。2.2 多平台适配一套定义全端同步开发者使用的工具链是多样的。你可能在VS Code里用Cursor写业务代码在终端里用Claude Code快速分析日志又在Zed里进行轻量编辑。goodai-base通过为每个技能提供多平台的定义文件解决了这个痛点。查看skills/feature-analyzer/目录你会看到SKILL.md # 用于 Claude Code SKILL.cursor.md # 用于 Cursor SKILL.codex.md # 用于 Codex SKILL.zed.md # 用于 Zed SKILL.opencode.md # 用于 OpenCode虽然核心逻辑相同但每个文件都根据目标AI工具的特性进行了微调。例如Cursor的.cursor.md文件可能会利用其独特的“”引用和代码库感知功能而Claude Code的.md文件则更侧重于其强大的长上下文和链式推理能力。项目提供的同步脚本sync-skills.ts会自动识别你的环境并将正确的文件复制到对应工具的配置目录下如~/.cursor/skills/。实操心得初次设置时建议通过安装向导完成。它会以交互方式询问你使用哪些工具并自动修改这些工具的全局配置文件如~/.cursor/rules/goodai-base.mdc注入路由指令。这比手动编辑要可靠得多能避免因路径或格式错误导致的技能失效。2.3 自治与追溯jobs/目录与执行记录goodai-base鼓励智能体进行自治程度较高的操作例如autodoc-orchestrator可以无人值守地扫描整个代码库并生成文档。为了确保可控和可追溯项目引入了jobs/目录的概念。当job-orchestrator这类编排类技能运行时它会在jobs/{timestamp}-{job-name}/目录下创建一个独立的工作空间。里面可能包含plan.md执行前生成的详细计划。context.md收集到的所有相关上下文信息。各个子任务sub-agent的输出文件。summary.md最终的任务总结报告。这个机制带来了两个好处透明化你可以随时查看AI的“工作笔记”了解它是如何分解问题、做出决策的这极大地增强了信任感。可恢复性如果任务执行中途被打断或者你对结果不满意你可以直接基于jobs/目录下的中间文件进行手动干预或让AI继续执行而不是从头开始。3. 核心技能深度解析与实战应用goodai-base包含了49个技能覆盖分析、审查、工作流、实现等十大类别。我们挑几个最具代表性、最能体现其设计深度的技能来拆解。3.1autodoc-orchestrator无人值守的代码库文档逆向工程这是我认为最能体现“智能体”价值的技能之一。它的目标是为一个陌生或缺乏文档的代码库自动生成结构清晰、内容准确的技术文档。它的5阶段自动化流水线如下扫描智能体首先会扫描项目根目录识别出主要的模块、目录结构、配置文件如package.json,pyproject.toml和入口文件建立一个初步的“地图”。并行分析基于扫描结果智能体会将代码库划分为多个逻辑模块如“用户认证服务”、“支付网关”、“前端组件库”然后并行地启动多个分析子智能体每个负责深入分析一个模块。这种并行化设计显著缩短了大型项目的分析时间。架构合成一个专用的架构师智能体会汇总所有并行分析的结果绘制出模块间的依赖关系图、数据流图并提炼出核心的架构模式和设计决策。并行编写同样采用并行策略多个文档编写智能体根据架构蓝图和模块分析结果同时撰写不同部分的文档如API参考、模块说明、部署指南等。最终汇编最后一个智能体负责将所有并行生成的文档片段进行整合、格式统一、交叉引用检查并生成最终的文档包通常是Markdown文件集合或一个静态站点。注意事项使用此技能前请确保你的代码库处于一个“可分析”的状态。如果项目依赖未安装或构建脚本失败智能体可能无法正确理解代码。建议先在一个干净的分支上运行npm install或poetry install等命令。另外对于非常庞大或结构异常复杂的项目可以考虑分模块多次运行每次指定特定的子目录作为扫描起点。实战命令示例在Claude Code中/autodoc-orchestrator --path ./src --output ./docs/generated这条命令会指示智能体分析./src目录下的代码并将生成的文档输出到./docs/generated目录。3.2review-orchestrator专业化、可定制的代码审查委员会传统的AI代码审查往往是一个“全能型专家”给出笼统的建议。review-orchestrator则模拟了一个专业的审查委员会它将审查任务拆解并分发给12个各有所长的专家。其工作流程如下接收请求你提交一段代码或一个PR链接。任务路由review-orchestrator作为调度员会解析代码的语言、框架和变更性质。并行审查它同时或按优先级调用以下子智能体review-logic: 检查业务逻辑缺陷、边界条件。review-architecture: 评估架构一致性、模块耦合度。review-security-code: 查找常见安全漏洞SQL注入、XSS等。review-performance: 分析算法复杂度、内存泄漏风险。review-frontend/review-backend: 针对特定技术栈的深度检查。review-greptile:亮点功能利用Greptile MCP服务理解代码变更在整个项目中的影响预测下游破坏。报告整合所有子智能体的发现被汇总并按照统一的严重性等级如阻塞、重要、建议进行归类生成一份结构化的审查报告。与Greptile的集成review-greptile子技能是一个游戏规则改变者。对于开源项目它可以免费调用Greptile的API。Greptile能够建立整个代码库的语义索引因此它的审查不是基于单文件的而是能指出“你这个修改了UserService的方法会影响到OrderController和NotificationScheduler等5个下游文件”。这种跨文件的影响分析是人类审查员都容易忽略的AI却能借助工具做得很好。实操心得为了让审查更有效我强烈建议在项目根目录维护一个rules/core/code-review-ai-assistant.mdc文件里面定义你团队特有的审查规则。例如“我们禁止在React组件内直接写console.log请使用自定义的debugLog工具函数”、“所有数据库查询必须使用参数化查询以防止SQL注入”。review-orchestrator会在审查时主动加载这些规则让审查标准与团队规范100%对齐。3.3job-orchestrator与feature-dev从任务到PR的端到端自动化这两个技能代表了AI智能体在软件开发工作流中的高阶应用。job-orchestrator是动态任务执行引擎。它的输入是一个模糊的、高级别的目标比如“为购物车添加优惠券功能”。它的工作步骤是上下文收集智能体会主动询问你或自行搜索代码库来理解“购物车”和“优惠券”的现有实现、数据模型、API接口。制定计划生成一个详细的、步骤化的执行计划plan.md并存入jobs/目录。计划可能包括“1. 在数据库中创建coupons表。2. 在CartService中添加计算折扣的逻辑。3. 在Order模型中增加折扣字段。4. 编写单元测试。”分派执行根据计划动态创建并管理一系列子任务sub-job。例如它会先调用task-implementer去创建数据库迁移文件再调用它去修改服务层代码最后调用tests-creator生成测试。进度追踪所有子任务的输入、输出和状态都被记录在jobs/目录下你可以随时查看进度。feature-dev则是一个更具体、更完整的特性开发流水线它预设了7个阶段需求澄清与你对话明确功能的验收标准。技术设计产出设计方案包括接口变更、数据库Schema、影响范围评估。实现进入编码阶段实质上是内部调用task-implementer。测试调用tests-creator生成单元和集成测试。审查调用review-orchestrator对生成的代码进行自我审查。修复基于审查反馈自动或在你确认后修复问题。创建PR生成格式良好的Commit Message和Pull Request描述。踩坑提醒完全依赖AI进行端到端开发目前仍有风险尤其是在复杂的、有状态的业务逻辑中。我的经验是将feature-dev用作“超级结对编程伙伴”。让它完成前6个阶段生成一个高质量的、经过自我审查的代码草稿和测试套件然后由你进行最终的人工复审和合并。这能将你的工作量从“从0到1创造”减少到“从80分到100分优化”效率提升非常显著。4. 规则系统团队知识的编码化如果说技能是AI的“肌肉”执行能力那么规则就是AI的“大脑皮层”判断标准。goodai-base的规则系统让你能将团队的无形知识固化下来。4.1 规则的组织与加载规则文件存放在rules/core/目录下以.mdc(Markdown with frontmatter) 格式存储。这种格式既方便人类阅读也便于AI解析其中的元数据如规则适用范围、优先级。规则不是被一次性全部加载的而是通过AGENTS.md中的逻辑进行动态匹配。例如AGENTS.md中可能有一段这样的逻辑- match: “用户请求中包含‘review’或‘审查’” action: “调用 review-orchestrator 技能并加载 rules/core/code-review-ai-assistant.mdc 规则” - match: “检测到当前文件是 .tsx 或 .ts 文件” action: “建议加载 rules/core/code-style-patterns.mdc 规则以获取TypeScript最佳实践”4.2 编写高质量规则的技巧一个有效的规则文件不仅仅是列表它应该包含原则为什么这条规则存在例如“优先使用函数组件而非类组件以拥抱React Hooks的简洁性和组合性。”正面示例展示符合规则的、理想的代码片段。反面示例展示常见的错误写法并解释其弊端。例外情况任何规则都有例外明确说明在什么情况下可以打破这条规则。自动化检查点如果可能指出这条规则是否可以通过ESLint、Prettier等工具自动执行。示例rules/core/commit-message-formatting.mdc的一部分--- title: “Git Commit Message 规范” scope: “所有Git提交” priority: “high” --- ## 原则 清晰的提交信息是项目可维护性的基石。它应能回答本次变更的**目的**是什么**影响**是什么 ## 格式 采用 [Conventional Commits](https://www.conventionalcommits.org/) 规范 type(scope): subject ## 类型 (type) * feat: 新功能 * fix: 修复bug * docs: 仅文档更改 * style: 不影响代码含义的更改空格、格式化等 * refactor: 既非新功能也非bug修复的代码重构 * test: 添加或修正测试 * chore: 构建过程或辅助工具的变动 ## 正面示例 feat(auth): 添加基于JWT的登录接口 fix(router): 修复动态路由参数在页面刷新后丢失的问题 ## 反面示例 更新了代码 过于模糊 修复bug 未说明是什么bug当AI需要生成或审查Commit Message时加载此规则就能产出符合团队规范的提交信息。5. 部署、配置与日常使用指南5.1 初始安装与配置最推荐的方式是使用项目提供的一键安装脚本curl -fsSL https://raw.githubusercontent.com/MrCipherSmith/goodai-base/main/install.sh | bash这个脚本会完成克隆仓库、安装依赖主要是Bun、并启动一个交互式配置向导。配置向导会引导你完成以下几个关键决策选择AI工具勾选你日常使用的所有工具Claude Code, Cursor, Zed等。向导会为每个工具注入正确的路由配置。设置工作目录环境变量GOODAI_JOBS_ROOT和GOODAI_DOCS_ROOT。默认jobs/和docs/generated/在项目目录内。如果你的项目在Docker容器或特定目录可以在这里修改确保AI生成的工作记录和文档存放在正确的位置。选择子智能体模型对于job-orchestrator这类会调用多个子任务的技能你需要指定子任务使用哪个AI模型如Claude的sonnet, opus, haiku。这关系到执行速度和成本。我的经验是对于分析、规划类任务用能力强的模型如opus对于简单的代码生成用更快的模型如haiku。TDD严格度选择是否强制要求“测试驱动开发”。如果开启“Iron Laws”模式task-implementer在写任何功能代码前必须先通过你定义的测试用例。这对于培养严谨习惯很有帮助但初期可能降低速度。语言偏好设置AI交互和生成内容的默认语言如英文AI术语或中英混合。5.2 日常使用模式配置完成后你的AI工具就“武装”上了goodai-base的技能。在Claude Code或Cursor中你可以这样使用直接调用技能在聊天输入框里输入/后你会看到所有已同步的技能列表就像使用Slash命令一样。输入/review-orchestrator并粘贴一段代码即可启动专业化审查。自然语言触发你也可以直接说“请分析一下feat/user-profile这个分支的架构影响。” AI通过读取AGENTS.md会自动识别出这应该调用feature-analyzer技能。在编辑器中右键在一些深度集成的编辑器如Cursor中选中代码后右键上下文菜单里可能会出现“使用goodai-base审查”等选项。同步与更新当你从团队仓库拉取了最新的技能或规则更新后需要运行同步命令cd ~/goodai-base/scripts bun run sync-skills如果只想同步到特定工具比如只更新Cursorbun src/sync-skills.ts --tools cursor5.3 项目结构与团队协作理解项目结构有助于团队协作和自定义扩展goodai-base/ ├── skills/ # 核心技能库 ├── rules/core/ # 核心规则库 ├── scripts/ # 同步、生成脚本 ├── docs/ # 自动生成的技能/规则目录由CI维护 └── jobs/ # 运行时工作记录.gitignore忽略团队协作流程建议Fork Pull Request团队成员不应直接修改主仓库的skills/和rules/core/。应该Fork仓库在各自的分支上开发新技能或修改规则。技能开发在skills/下新建目录参考现有技能的结构编写多平台的定义文件。重点描述清晰的输入、输出、执行步骤和错误处理。规则制定在rules/core/下新增或修改.mdc文件。规则变更应经过团队讨论因为它会影响所有AI助手的输出。更新AGENTS.md如果新技能需要被路由调用或新规则需要被关联可能需要修改AGENTS.md中的匹配逻辑。这是一项需要谨慎的操作。CI验证项目配置了GitHub Actions任何对skills/或rules/的推送都会自动重新生成docs/下的目录文件确保文档与代码同步。6. 常见问题、排查技巧与进阶玩法6.1 常见问题速查表问题现象可能原因解决方案输入/后看不到技能列表技能未正确同步到AI工具目录1. 运行bun run sync-skills --all强制同步所有工具。2. 检查目标目录如~/.cursor/skills/是否存在且文件完整。3. 重启你的AI工具/编辑器。AI无法识别命令或调用了错误的技能AGENTS.md路由逻辑未正确注入全局配置1. 重新运行配置向导bun ~/goodai-base/setup.ts --reconfigure。2. 手动检查对应工具的全局指令文件如~/.cursor/rules/goodai-base.mdc是否包含指向AGENTS.md的引用。job-orchestrator执行失败报错找不到路径GOODAI_JOBS_ROOT环境变量未设置或指向错误1. 确认配置向导中已正确设置工作目录。2. 在终端中执行echo $GOODAI_JOBS_ROOT查看当前值。3. 在shell配置文件如.zshrc中永久设置该变量。规则似乎没有生效规则文件语法错误或AGENTS.md中的匹配条件不满足1. 检查对应的.mdc文件确保Markdown和frontmatter格式正确。2. 在AI会话中尝试手动输入指令请加载规则code-style-patterns看AI是否能正确读取并应用。技能执行速度很慢可能调用了多个子智能体且配置了大型号模型如opus1. 在配置向导中为子任务选择更快的模型如haiku。2. 对于非关键路径的分析任务考虑使用--fast模式如果技能支持。6.2 性能优化与成本控制模型选择策略在setup.ts向导中仔细配置“子智能体模型”。一个推荐的策略是让主协调器如job-orchestrator使用能力最强的模型如opus来做规划和决策而让具体的执行子任务如写一个工具函数使用更经济快速的模型如haiku。上下文管理goodai-base的动态加载机制本身就是为了优化上下文。确保你的规则文件写得精炼、切中要害避免包含大量示例代码而挤占有效上下文。缓存结果对于feature-analyzer或autodoc-orchestrator这类分析型技能其结果在一定时间内是稳定的。你可以将AI生成的报告位于jobs/或输出目录手动或通过脚本进行缓存在下次询问类似问题时直接让AI参考缓存文件而不是重新分析整个代码库。6.3 自定义扩展打造属于你团队的技能goodai-base的真正威力在于它的可扩展性。假设你的团队使用一个特定的内部框架或有一套独特的部署流程你可以轻松地为其创建技能。创建自定义技能的步骤在skills/下创建目录例如skills/deploy-to-internal-k8s/。创建平台定义文件至少创建SKILL.md(Claude Code) 和SKILL.cursor.md。你可以从现有技能如deploy/复制一个作为模板。编写技能逻辑在文件中清晰地定义描述这个技能是做什么的输入它需要哪些参数例如服务名、镜像标签、环境执行步骤一步一步地描述AI应该做什么。例如1. 检查当前分支是否干净。2. 运行单元测试。3. 构建Docker镜像并推送到内部仓库。4. 生成K8s deployment yaml。5. 使用kubectl apply部署。输出最终应该生成什么例如部署成功的确认、Pod状态查看命令、回滚指令。可选更新AGENTS.md如果你希望AI能自动识别何时调用这个新技能需要在AGENTS.md中添加一条匹配规则。例如当用户输入包含“部署到测试环境”时触发此技能。运行同步脚本然后就可以在你的AI工具中通过/deploy-to-internal-k8s来调用它了。通过这种方式你可以将团队里任何重复性的、有固定模式的知识型工作都封装成AI技能极大地提升整体工程效能的一致性。