构建团队AI知识库：统一工程实践与自动化工作流

1. 项目概述：一个为工程团队设计的AI技能与规则知识库

如果你和我一样，每天在Claude Code、Cursor这些AI编程工具里反复输入类似的提示词，比如“帮我分析一下这个PR的架构影响”、“用NestJS风格写个DTO”、“按我们的规范生成提交信息”，那你肯定也烦了。这种重复劳动不仅低效，还容易导致输出质量参差不齐，因为每次提示的措辞、上下文都可能略有不同。goodai-base这个项目，就是为了彻底解决这个问题而生的。

简单来说，它不是一个普通的提示词合集，而是一个精心编排的、面向真实工程团队的AI智能体技能与规则知识库。它的核心思想是“定义一次，处处使用”。你把团队里那些经过验证的、高效的AI工作流（它称之为Skills）和必须遵守的编码规范、审查标准（它称之为Rules）定义好，然后通过一个同步脚本，一键分发到你团队所有成员使用的AI工具（Claude Code, Cursor, Codex, Zed, OpenCode）中。从此，无论是谁，在哪个项目里，只要输入一个简单的斜杠命令，比如/feature-analyzer，就能触发一个复杂的、多步骤的、高质量的分析流程，输出结果始终符合团队标准。

这背后的价值，远不止是节省打字时间。它意味着团队协作的“AI副驾驶”有了统一的操作手册和标准作业程序（SOP）。新成员 onboarding 时，不再需要口口相传“怎么让AI更好地帮我们干活”；代码审查时，AI能基于团队统一的“审查官”角色给出更一致、更专业的反馈；在实施复杂功能时，AI能像一个经验丰富的工程师一样，遵循预设的、包含需求分析、设计、实现、测试、审查的完整工作流。goodai-base试图将AI从一种“灵光一现”的辅助工具，转变为团队开发流程中一个稳定、可靠、可预测的自动化环节。

2. 核心组件深度解析：Skills与Rules的设计哲学

要真正用好goodai-base，不能只停留在“安装即用”的层面，必须理解其两大核心组件Skills和Rules的设计哲学与运作机制。这决定了你如何定制它，以及它如何从根本上提升你的工程效率。

2.1 Skills：可编排的智能体工作流

Skills是goodai-base的“肌肉”和“动作”。每个Skill都定义了一个完整的、目标明确的AI智能体工作流。它不是一句简单的提示，而是一个多步骤、有状态、可协作的剧本。

2.1.1 Skill的架构与多平台适配

每个Skill都位于skills/<skill-name>/目录下，其精妙之处在于为不同AI工具提供了平台特定的定义文件。例如，skills/feature-analyzer/目录下可能包含：

• SKILL.md: 用于 Claude Code 的原始定义。
• SKILL.cursor.md: 针对 Cursor 的交互和上下文特性进行了优化。
• SKILL.codex.md: 适配 Codex 的语法和功能集。

这种设计确保了同一个工作流逻辑，能在不同工具的生态环境下以最自然的方式运行。当你运行同步脚本时，goodai-base会智能地将对应的文件复制到各工具的技能目录中（如~/.claude/skills/），实现无缝集成。

2.1.2 代表性Skill工作流拆解

让我们深入几个核心Skill，看看它们是如何将复杂任务自动化的：

• autodoc-orchestrator(自动文档生成管道)：这不仅仅是一个“生成文档”的命令。它是一个完全自主的5阶段反向工程管道：

  1. 扫描阶段：智能体首先扫描整个代码库，识别所有模块和文件结构。
  2. 并行分析阶段：将不同模块分配给多个“子分析员”智能体（或在单次会话中分步执行），并行分析每个模块的职责、接口和依赖。
  3. 架构合成阶段：一个“架构师”智能体汇总所有分析结果，绘制出系统的整体架构图和数据流。
  4. 并行编写阶段：基于合成后的架构，多个“文档撰写员”智能体并行为不同模块编写详细的API文档、README和组件说明。
  5. 最终汇编阶段：一个“汇编员”智能体将所有文档片段整合、校验链接、生成统一的目录和导航，输出一个完整的文档包。

  注意：这个流程是“无人工闸门”的，意味着一旦触发，它会自主运行到底。这非常适合在项目初期或缺乏文档时快速建立基线文档，但对于频繁变更的活跃分支，可能需要结合gproject-orchestrator的人类审核节点。

• review-orchestrator(审查协调器)：这是一个经典的“调度员”模式。当你对一段代码执行/review时，这个Skill并不会自己审查所有方面，而是扮演一个调度中心：

  1. 请求解析：分析待审查代码的语言、框架和变更范围。
  2. 智能路由：根据解析结果，将审查任务分发给多达12个专业子审查员（review-logic,review-architecture,review-security-code等）。
  3. 结果聚合：收集所有子审查员的报告，统一严重性等级（如将各子项的“高危”统一为“阻断”），合并重复建议，生成一份结构清晰、优先级分明的综合审查报告。 这种设计避免了单一、笼统的审查提示，使得安全漏洞、性能瓶颈、架构异味、代码风格问题都能由“最专业的AI”来诊断，审查质量远高于通用提示。

• job-orchestrator(任务协调器)：这是实现复杂、长周期任务的引擎。它会在项目根目录下创建一个jobs/文件夹（可配置），为每个任务会话建立独立的工作区。

  1. 上下文收集：首先与用户对话，明确任务目标、约束条件和相关上下文。
  2. 计划制定：将宏任务分解为一系列原子子任务，并制定执行计划。
  3. 子任务分发与执行：按计划调用其他Skills（如task-implementer,tests-creator）来执行每个子任务。
  4. 进度跟踪与文档化：在整个过程中，它在jobs/<job-id>/目录下详细记录决策日志、生成的代码、测试结果和遇到的问题，实现完全的可追溯性。这对于调试AI生成代码的逻辑、复盘复杂任务的执行过程至关重要。

2.2 Rules：按需加载的编码标准

如果说Skills是“怎么做”，那么Rules就是“做成什么样”。Rules是团队编码标准的机器可读版本，存放在rules/core/目录下，以.mdc格式存储。

2.2.1 Rules与Skills的关键区别：按需加载

这是goodai-base一个非常关键的设计决策：Rules不是始终加载的全局上下文。很多团队尝试将长长的编码规范全部塞进AI工具的“自定义指令”，导致上下文窗口被大量不相关的信息占用，稀释了核心任务的注意力，甚至可能干扰AI的判断。

goodai-base的Rules采用“按需加载”机制。AGENTS.md文件作为路由表，会观察用户的请求。当AI识别出当前请求涉及特定领域时（例如，用户要求“创建一个React组件”），路由逻辑会指示AI动态加载对应的Rule文件（如frontend-assistant.mdc）。这意味着，在讨论后端API时，前端Rule不会出来“刷存在感”；在写提交信息时，测试相关的Rule才会被激活。这极大地提升了上下文利用效率，让AI在特定领域表现得更加专业。

2.2.2 核心Rules类别与应用场景

• 代码审查规则(code-review-ai-assistant.mdc,code-review-boss-profile.mdc)：这定义了AI在审查代码时应扮演的角色、审查的严格程度、反馈的语气（是温和建议还是严厉要求）以及必须检查的清单。你可以为不同成熟度的项目或团队配置不同的“审查官”角色。
• 技术栈规则(nestjs-dto.mdc,mobx-store-template.mdc,code-style-patterns.mdc)：这些是具体的实现模板和模式。例如，nestjs-dto.mdc可能规定了团队内创建Data Transfer Object时必须使用的装饰器、验证库（class-validator）、序列化选项（excludeExtraneousValues）以及文档字符串格式。AI在生成相关代码时会严格遵循此模板。
• 流程规则(implementation-plans.mdc,git-rules.mdc)：这些规则规范了开发流程。git-rules.mdc可能定义了提交信息的格式（Conventional Commits）、分支命名策略、PR描述模板。implementation-plans.mdc则可能要求AI在开始编码前，必须先输出一个包含技术方案选型、风险评估、任务拆解和预估工时的实施计划，经人工确认后才能继续。

3. 从安装到实战：构建你的AI辅助工作流

理解了核心概念后，我们来一步步搭建并运用这套系统。我将以最常用的Claude Code和Cursor为例，带你走完从安装、配置到日常使用的全过程，并分享一些关键的实操心得。

3.1 环境准备与一键安装

3.1.1 前置条件检查

在运行安装脚本前，请确保你的系统满足以下条件：

1. Bun 运行时：goodai-base的脚本工具链基于 Bun。如果你还没有安装，可以访问 bun.sh 获取一键安装命令。Bun相比Node.js在脚本启动速度和API友好性上更有优势，这也是项目选型它的原因。
2. Git：用于克隆仓库。
3. 目标AI工具：至少安装并初步配置了 Claude Code、Cursor、Codex、Zed 或 OpenCode 中的一种。确保你知道它们的配置目录在哪里（通常是用户主目录下的隐藏文件夹）。

3.1.2 执行一键安装与配置向导

官方推荐的一行命令安装是最佳起点：

curl -fsSL https://raw.githubusercontent.com/MrCipherSmith/goodai-base/main/install.sh | bash

这个命令会：

1. 从GitHub拉取最新的goodai-base代码库到你的~/goodai-base目录。
2. 进入scripts目录并使用 Bun 安装项目依赖。
3. 启动交互式配置向导。这是整个安装的核心，务必仔细完成。

3.1.3 配置向导详解与选型建议

向导会依次询问你以下几个关键配置，你的选择将决定goodai-base如何融入你的工作流：

1. 选择同步的AI工具：你可以全选，也可以只选你常用的。我建议至少勾选 Claude Code 和 Cursor，因为它们的用户群最广，Skills的适配也最成熟。
2. 全局配置注入：向导会向每个选定工具的全局指令文件（如 Claude Code 的~/.claude/CLAUDE.md，Cursor 的~/.cursor/rules/goodai-base.mdc）插入一个“路由块”。这个块的作用是告诉AI工具：“当你收到用户请求时，先来看看AGENTS.md这个路由表，看看有没有预定义的Skill或Rule可以处理”。这是实现技能调度的关键一步，务必允许注入。
3. 工作与文档根路径：你可以设置环境变量GOODAI_JOBS_ROOT和GOODAI_DOCS_ROOT来指定job-orchestrator生成的任务文档和项目文档的存放位置。默认是在项目根目录下的jobs/和docs/文件夹。如果你希望所有项目的AI任务日志都集中管理，可以在这里设置为一个全局路径，例如~/ai_work_logs/。
4. 子智能体模型选择：当Skills调用其他AI子任务时（例如review-orchestrator调用各个子审查员），使用什么模型？选项通常是 Claude 3 系列（Sonnet, Opus, Haiku）。这里有一个权衡：
   • Haiku：速度最快，成本最低，适合逻辑简单、追求速度的任务（如代码风格检查）。
   • Sonnet：在速度、成本和能力上取得平衡，是大多数场景下的推荐选择。
   • Opus：能力最强，但速度慢、成本高，仅用于最复杂、最需要创造性和深度推理的任务（如架构设计、模糊问题定义）。

   实操心得：对于日常开发，我选择Sonnet 作为默认子智能体。对于gproject-orchestrator（项目文档生成）这类重型任务，我会在调用时临时指定使用 Opus 模型，以获取更高质量的输出。

5. TDD（测试驱动开发）执行严格度：这决定了task-implementer等实现类Skill的行为。
   • 严格模式（Iron Laws）：AI必须在编写任何实现代码前，先编写失败的测试用例。这强制遵循TDD循环，适合对代码质量要求极高、测试覆盖率是硬性指标的项目。
   • 宽松模式（仅修复任务）：只有在进行缺陷修复（bug fix）时，才要求先写测试。对于新功能开发，允许先实现后补测试。这种模式更灵活，开发速度更快。

   注意：如果你的团队尚未形成严格的TDD文化，初期建议选择“宽松模式”，避免AI因无法理解如何为先不存在的功能写测试而陷入死循环。

6. 语言偏好：设置AI输出和交互的默认语言。选项通常支持多语言混合（如ru+en+ai表示俄语、英语和AI术语）、纯英语加AI术语（en+ai）或纯英语（en）。根据你和团队的主要沟通语言选择即可。

完成向导后，安装脚本会自动执行首次同步，将Skills和AGENTS.md文件复制到你选择的AI工具目录中。

3.2 核心技能实战演练

安装配置完成后，我们进入真正的实战环节。打开你的 Claude Code 或 Cursor，新建一个聊天会话或编辑器，就可以开始使用Skills了。

3.2.1 场景一：深度分析新功能分支（/feature-analyzer）

假设你刚拉取了一个同事创建的名为feat/user-onboarding-v2的分支，你需要快速理解它的改动范围和架构影响。

在AI聊天框中输入：

/feature-analyzer

然后按照AI的提示，提供分支名称feat/user-onboarding-v2。

接下来，feature-analyzerSkill 会启动一个多步骤的分析流程：

1. 差异提取：AI会首先执行git diff相关命令，获取该分支与主分支（或目标分支）的所有代码差异。
2. 影响面分析：它会逐文件分析改动，识别出：
   • 新增了哪些模块、组件或API端点。
   • 修改了哪些核心业务逻辑。
   • 删除了哪些废弃功能。
3. 依赖与耦合度检查：分析改动的文件影响了哪些其他模块（导入关系）、数据库表结构是否变更、外部服务接口是否有调整。
4. 架构评估：基于团队的架构规则（如果相关Rule已加载），评估这些改动是否符合既定的设计模式（如是否引入了循环依赖、是否破坏了分层架构、状态管理是否合理）。
5. 生成综合报告：最终，它会输出一份结构化的报告，通常包含：
   • 摘要：改动统计（文件数、行数）。
   • 核心变更：列表说明主要改了哪里。
   • 架构影响：高、中、低风险标识及说明。
   • 测试建议：指出哪些区域需要重点补充测试。
   • 合并前检查清单：提醒你合并前需要确认的事项（如数据库迁移、配置更新、文档更新）。

   避坑技巧：对于非常大的分支，AI可能因上下文限制无法一次性分析所有差异。此时，你可以引导它先分析最重要的或最先修改的目录。更好的做法是，在团队协作中，鼓励小批量、频繁提交，这样feature-analyzer的效果最佳。

3.2.2 场景二：发起一次全面的代码审查（/review）

当你完成一段代码编写，或者收到一个Pull Request时，可以使用审查技能。

在AI聊天框中输入：

/review

然后粘贴你需要审查的代码块，或者直接让AI分析当前打开的文件。

review-orchestrator开始工作：

1. 调度：它识别代码语言（如TypeScript + React）和上下文，然后决定调用哪些子审查员。对于这段代码，它可能会并行（在AI内部模拟）或依次调用review-logic（业务逻辑）、review-frontend（React最佳实践）、review-style（代码风格）、review-security-code（安全漏洞）等。
2. 收集与整合：每个子审查员提交自己的报告，指出问题并给出建议。review-orchestrator会做去重和优先级排序。例如，review-style可能指出“变量名应使用camelCase”，而review-logic可能发现一个潜在的空值错误。
3. 输出统一报告：你最终得到的是一份整合报告，问题会按严重性（阻断、高危、中危、建议）分类，并且每个问题都标注了是由哪个审查领域发现的。这比一句笼统的“这里可能有bug”要 actionable 得多。

   实操心得：不要完全依赖AI审查。将其视为第一道自动化防线和知识传递工具。对于AI指出的问题，尤其是架构和安全方面，一定要人工复核。同时，这个过程也是让团队新人学习编码规范的好机会——他们可以看到AI是如何根据code-style-patterns.mdc等规则来评审代码的。

3.2.3 场景三：自动化实现一个复杂任务（/job-orchestrator）

假设你需要实现一个“用户上传图片后生成缩略图并存储到S3”的功能。这是一个涉及多个步骤（接收文件、验证、处理图片、调用云服务、更新数据库）的复合任务。

在AI聊天框中输入：

/job-orchestrator

AI会启动交互式任务规划：

1. 目标澄清：它会问你：“请描述需要实现的任务目标、技术栈要求和任何约束条件。” 你详细描述需求。
2. 计划制定：基于你的输入，它生成一个执行计划，可能包括：
   • 子任务1：分析现有项目结构，定位到处理文件上传的控制器和服务。
   • 子任务2：编写图片处理工具函数（使用Sharp库），包含生成多种尺寸缩略图的逻辑。
   • 子任务3：集成AWS SDK，编写将文件上传至S3的Service。
   • 子任务4：修改现有的上传逻辑，串联起验证、处理、上传、保存URL到数据库的流程。
   • 子任务5：为新增的函数和Service编写单元测试。
   • 子任务6：更新API文档。
3. 逐项执行与确认：job-orchestrator会按照计划，依次调用task-implementer、tests-creator等Skill来执行每个子任务。关键点在于：它通常会在每个关键步骤后暂停，并征求你的确认（“子任务1已完成，这是分析报告和代码定位。是否继续执行子任务2？”）。这给了你控制权，可以在任何时候介入、调整方向或中止任务。
4. 全程记录：所有对话、生成的代码、遇到的问题和解决方案，都会被记录在jobs/<job-id>/目录下的Markdown文件中。这个日志文件是无价之宝，不仅用于回溯，当任务因故中断后，你可以将日志提供给AI，它能快速恢复上下文，继续执行。

3.3 自定义与扩展：打造团队专属知识库

goodai-base的真正威力在于其可定制性。开源仓库里的49个Skills和17个Rules只是起点，你需要将其转化为自己团队的“数字资产”。

3.3.1 创建自定义Skill

假设你的团队大量使用GraphQL，并且有一套独特的Resolver编写规范和数据加载优化模式（如使用DataLoader避免N+1查询）。你可以创建一个graphql-resolverSkill。

1. 创建Skill目录：在skills/目录下新建graphql-resolver/。
2. 编写平台定义文件：至少创建SKILL.md(Claude Code) 和SKILL.cursor.md。

   # SKILL.md (Claude Code 版本) ## Skill: graphql-resolver **Description:** 根据团队规范，生成或重构一个GraphQL Resolver。规范包括：使用DataLoader批处理数据查询、统一的错误处理中间件、遵循特定的命名约定、以及自动生成JSDoc注释。 **Workflow:** 1. 请用户提供要处理的GraphQL类型名称和字段，或直接粘贴现有Resolver代码。 2. 分析现有代码库中的Resolver模式，确保风格一致。 3. 根据团队 `rules/core/graphql-best-practices.mdc`（如果存在）中的规则生成或重构代码。 4. 重点确保数据库查询使用了DataLoader进行批量化。 5. 生成的代码必须包含符合规范的JSDoc注释，说明参数、返回值和可能的错误。 6. 询问用户是否需要在同一模块中创建或更新对应的单元测试桩。 **Invocation:** `/graphql-resolver`

3. 更新路由表：在AGENTS.md文件中，添加一条新的路由规则，告诉AI当用户请求与“graphql”、“resolver”相关时，触发这个新Skill。

   - trigger: ["graphql resolver", "create resolver", "写一个graphql查询"] skill: "graphql-resolver" rule: "graphql-best-practices" # 关联一个自定义的Rule文件

4. 同步：运行bun scripts/sync-skills.ts，将新Skill同步到你的AI工具中。

3.3.2 创建自定义Rule

继续上面的例子，创建rules/core/graphql-best-practices.mdc。

# GraphQL 最佳实践 (MyTeam Edition) ## 1. Resolver 结构 - 所有Resolver必须放在 `src/graphql/resolvers/` 目录下，按类型分文件。 - 每个Resolver函数必须是 `async` 函数。 - 使用 `Resolver` 装饰器（如果使用NestJS）或标准的函数签名。 ## 2. 数据加载 - **严禁**在Resolver中直接进行数据库循环查询。 - 必须使用 `DataLoader` 实例。实例已在上下文 `ctx.loaders` 中提供。 - 批量加载函数应定义在 `src/graphql/loaders/` 目录下。 ## 3. 错误处理 - 业务错误使用 `ApolloError` 或自定义的 `UserInputError` 抛出。 - 系统错误应在顶层由 `ApolloServer` 插件统一记录，不应在Resolver中 `console.error`。 ## 4. 文档 - 每个Resolver函数上方必须有JSDoc注释。 - 注释格式： /** * 描述该Resolver的功能。 * @param {ParentType} parent - 父字段的返回值。 * @param {ArgsType} args - GraphQL调用参数。 * @param {ContextType} ctx - 请求上下文，包含用户、数据库连接、DataLoader等。 * @returns {Promise<ReturnType>} 返回值的描述。 * @throws {ApolloError} 可能抛出的错误类型及条件。 */

创建完成后，同样需要同步。现在，当你的团队任何成员使用/graphql-resolverSkill时，AI就会自动加载这套规则，生成完全符合团队标准的代码。

4. 高级技巧、问题排查与效能提升

在深度使用goodai-base一段时间后，我积累了一些能极大提升体验和效率的高级技巧，也总结了一些常见问题的排查方法。

4.1 效能提升与高级用法

4.1.1 技能组合与流水线作业

最强大的用法不是单独使用某个Skill，而是将它们串联起来，形成一个自动化流水线。例如，处理一个GitHub Issue的完整流程可以是：

1. /issue-analyzer：将Issue描述拆解成具体的开发任务清单。
2. /job-orchestrator：将任务清单作为输入，规划并执行整个开发流程，期间它会自动调用task-implementer、tests-creator。
3. /review-orchestrator：在job-orchestrator生成代码后，自动对代码进行审查。
4. /commit与/pr：使用定义好的Git规则生成规范的提交信息，并起草Pull Request描述。

你可以通过编写一个简单的Shell脚本或使用项目的scripts/目录下的工具，将这些步骤半自动化，甚至结合GitHub Actions，在Issue创建时自动触发分析。

4.1.2 利用AGENTS.md进行精细路由

AGENTS.md文件是大脑。花时间精心设计它的路由逻辑，能让AI更“聪明”地理解你的意图。路由规则不仅基于关键词，还可以基于上下文、文件类型等。例如，你可以设置：

• 当用户在React组件文件中提问时，优先加载frontend-assistant规则。
• 当对话内容包含“安全”、“漏洞”、“注入”等词时，自动触发security-auditSkill的提醒。
• 对于以“如何测试...”开头的问题，直接引导至tests-creatorSkill。

4.1.3 环境变量与配置分离

对于团队协作，硬编码的API密钥、服务器地址等敏感信息不应放在Skill或Rule文件中。goodai-base支持通过环境变量注入配置。你可以在Skill的提示词中使用{{ENV_VAR_NAME}}这样的占位符，然后在运行AI工具前设置相应的环境变量。更优雅的做法是使用.env.local文件（不被提交到Git），并在团队的安装文档中说明如何配置。

4.2 常见问题排查速查表

即使设计再精良，在实际使用中也可能遇到问题。下表总结了常见问题及其解决方法：

4.3 维护与团队协作建议

goodai-base作为一个活的、不断演进的知识库，需要一定的维护。

1. 版本控制与Code Review：将你团队定制后的skills/和rules/目录纳入Git版本控制。对Skill和Rule的修改，应该像修改源代码一样发起Pull Request，并经过团队其他成员的审查。这能保证知识库的质量和一致性。
2. 定期回顾与更新：技术栈和最佳实践在变化。每个季度或每半年，团队应该一起回顾现有的Skills和Rules，看是否有过时的模式需要更新，或者是否有新的常用工作流可以沉淀为Skill。
3. 渐进式采用：不要试图一次性引入所有49个Skill。从最痛点开始，比如先统一commit消息格式和code-review标准。等团队适应后，再逐步引入feature-analyzer、job-orchestrator等更复杂的技能。让工具适应团队，而不是让团队适应工具。
4. 建立反馈渠道：在团队内部建立一个简单的反馈机制（如一个专门的Slack频道或GitHub Discussion），让大家分享使用某个Skill的心得、遇到的问题，或者提出改进建议。这些反馈是优化Skill提示词的最宝贵材料。

我个人在实际使用中的体会是，goodai-base带来的最大转变，是让AI辅助编程从“个人魔术”变成了“团队工程”。它减少了沟通成本，提升了输出的一致性，并将团队的最佳实践固化成了可执行、可迭代的数字资产。初期投入一些时间进行定制和磨合是值得的，一旦这套系统运转起来，它将成为团队研发效能中一个稳定而强大的加速器。最后一个小技巧是，多看看jobs/目录下的日志，你不仅能发现AI执行任务的逻辑，还能从中提炼出新的、可自动化的模式，反过来继续丰富你的goodai-base知识库。