为Kubeflow Notebooks项目定制AI编码助手：提升大型开源项目开发效率

1. 项目概述：为Kubeflow Notebooks项目引入AI编码助手规范

如果你正在参与Kubeflow Notebooks这类大型开源项目的开发，尤其是在notebooks-v2这样的重构分支上工作，你可能会发现一个痛点：项目太大了。前后端分离，控制器逻辑复杂，再加上E2E测试，每个模块都有自己的技术栈和代码规范。当你打开一个不熟悉的目录，想用Claude Code或Cursor这类AI助手快速生成或修改代码时，AI往往因为缺乏项目上下文，给出一些“通用但错误”的建议，比如在前端用错了状态管理库，或者在Go后端写出了不符合项目约定的错误处理逻辑。结果就是你得花大量时间手动纠正，AI的提效作用大打折扣。

caponetto/kubeflow-notebooks-ai-rules这个项目，就是为了解决这个“上下文缺失”的问题而生的。它不是一个独立的工具，而是一套精心设计的“AI助理上岗培训手册”。简单来说，它把Kubeflow Notebooks项目中，那些只有核心贡献者才心知肚明的开发规范、最佳实践、常见陷阱，整理成了AI能直接读取和理解的配置文件（主要是AGENTS.md和SKILL.md）。当你把这个项目通过软链接“安装”到你的Kubeflow Notebooks工作目录后，你的AI编码助手就能自动读取这些规则，生成的代码会立刻变得“地道”起来，仿佛一个老练的项目成员在帮你写代码。

这套规则的核心价值在于“约束与引导”。它不仅仅告诉AI“应该怎么写”，更重要的是划定了“绝对不能怎么写”的红线。比如，在控制器模块的AGENTS.md里，可能会明确规定“禁止在Reconcile循环中直接调用Kubernetes API Server，必须使用client-go的缓存机制”，这就避免了新手（包括AI）常犯的性能问题。对于前端，它可能规定了组件必须使用函数式组件配合Hooks，状态管理必须通过特定的Context，从而保证代码风格的一致性。这套机制特别适合团队协作和新人 onboarding，能极大降低代码审查的成本，让AI真正成为符合项目标准的“生产力倍增器”，而不是需要反复纠正的“实习生”。

2. 核心设计思路：分层引导与技能解耦

这个项目的架构设计非常巧妙，它没有采用一个臃肿的、包含所有规则的大文件，而是采用了“分层引导”和“技能解耦”的策略。理解这个设计，是高效使用和后续扩展它的关键。

2.1 全局策略与模块专属规则的分离

项目根目录下的agents/AGENTS.md文件，扮演的是“宪法”的角色。它定义了整个Kubeflow Notebooks项目必须遵守的、跨所有模块的顶层规则。这些通常是最高优先级的“MUST”和“MUST NOT”条款。例如：

• 代码安全：禁止引入已知的安全漏洞模式，如不安全的依赖版本、硬编码的密钥。
• 提交规范：Commit message必须遵循特定格式（如Conventional Commits），PR描述必须包含清晰的上下文和验收标准。
• 通用开发守则：代码必须通过所有静态检查（如ESLint、gofmt、golangci-lint），新增功能必须包含测试等。

而在agents/backend/、agents/frontend/等子目录下的AGENTS.md文件，则是针对特定技术栈的“部门规章”。它们继承并细化了全局规则。例如，agents/frontend/AGENTS.md会详细规定：

• 组件设计：React组件必须使用TypeScript，优先使用函数组件，Props必须定义明确的接口。
• 状态管理：全局状态使用Redux Toolkit还是React Context？如何划分slice？
• API交互：必须使用项目封装的apiClient，错误处理必须统一捕获并转换为用户友好的提示。
• 样式方案：是使用CSS Modules、Styled Components还是Tailwind？类名命名规范是什么？

这种分离的好处是，当AI在处理workspaces/frontend/src/components/下的文件时，它会同时读取全局规则和前端专属规则，获得最精准的上下文，而不会被无关的后端或控制器规则干扰。

2.2 稳定策略与动态技能的混合模型

这是项目最精妙的设计之一。AGENTS.md文件被设计为承载“稳定的策略和边界”。这些内容相对固定，比如项目选型、架构原则、安全红线，不会因为实现一个具体功能而频繁变动。

而skills/目录下的SKILL.md文件，则被设计为“动态的、任务导向的工作流”。你可以把它理解为一份份针对特定开发任务的“标准作业程序”。例如，可能会有一个skills/kubeflow-notebooks-frontend-api-integration/SKILL.md，它详细描述了：“当需要在前端集成一个新的后端API时，你应该遵循以下步骤：1. 在src/api/types.ts中定义TypeScript接口；2. 在src/api/endpoints.ts中添加API路径常量；3. 在src/api/client.ts中创建对应的请求函数，并处理错误；4. 在相应的React组件或Hook中调用该函数，并管理loading和error状态。”

为什么这么设计？

1. 降低提示词长度：AI处理长上下文有成本和性能限制。如果把所有技能细节都塞进AGENTS.md，文件会变得极其臃肿。通过技能解耦，AI在需要执行特定任务时，才去动态加载对应的SKILL.md，保证了核心策略文件AGENTS.md的简洁和高效加载。
2. 提升可维护性：当某个任务的工作流需要更新时（比如API响应格式变了），你只需要修改对应的SKILL.md，而无需触碰稳定的AGENTS.md策略文件。
3. 符合开放标准：项目遵循了agentskills.io的规范，将技能文件统一软链接到.agents/skills/目录下。这意味着未来任何支持该标准的AI工具，都能自动发现和利用这些技能，具备了很好的工具兼容性和可移植性。

注意：在编写SKILL.md时，要确保它们是原子化的、可独立执行的。一份好的技能文档应该像一份优秀的菜谱，有明确的输入、清晰的步骤、和预期的输出。

3. 实战部署与集成指南

理解了设计理念，下一步就是把它用起来。部署过程不复杂，但有几个关键细节需要特别注意，否则可能会遇到软链接失效或意外提交的问题。

3.1 环境准备与仓库克隆

首先，你需要一个正确的工作目录结构。假设你的开发根目录是~/dev，操作如下：

# 1. 进入你的开发目录 cd ~/dev # 2. 克隆AI规则仓库 git clone git@github.com:caponetto/kubeflow-notebooks-ai-rules.git # 3. 克隆Kubeflow Notebooks仓库（注意指定notebooks-v2分支） # 如果你有项目fork，将 `kubeflow` 替换为你的GitHub用户名 git clone -b notebooks-v2 git@github.com:kubeflow/notebooks.git kubeflow-notebooks

这里的关键是分支。这个AI规则集是针对notebooks-v2分支的结构和代码规范设计的。如果你在main或其他分支上使用，规则文件指向的目录路径或代码规范可能不匹配，导致AI给出错误指导。务必确认你当前开发所基于的分支。

3.2 执行安装脚本与原理剖析

安装的核心是运行项目提供的脚本：

cd ~/dev/kubeflow-notebooks-ai-rules ./scripts/install.sh ~/dev/kubeflow-notebooks

这个install.sh脚本做了以下几件重要的事，理解它们有助于排查问题：

1. 读取映射配置：脚本首先会读取agents/mappings.conf文件。这个文件定义了源文件（在AI规则仓库内）和目标软链接路径（在Kubeflow Notebooks仓库内）的对应关系。例如，它可能指定将agents/frontend/AGENTS.md软链接到kubeflow-notebooks/workspaces/frontend/AGENTS.md。
2. 创建目录软链接：对于skills/目录下的每个技能，脚本会在Kubeflow Notebooks仓库的根目录创建.agents/skills/目录（如果不存在），并为每个技能创建软链接。这是遵循agentskills.io标准，让AI工具能自动扫描发现技能。
3. 创建文件软链接：根据mappings.conf，在各个模块目录下创建AGENTS.md和CLAUDE.md的软链接。
4. 处理Claude兼容性：CLAUDE.md本身就是一个指向根AGENTS.md的软链接。这是因为Claude Code工具默认会寻找并读取项目根目录下的CLAUDE.md文件。这个设计确保了Claude用户无需额外配置。

安装完成后，你的kubeflow-notebooks目录结构会多出这些“幽灵文件”（软链接）：

kubeflow-notebooks/ ├── .agents/ │ └── skills/ -> ~/dev/kubeflow-notebooks-ai-rules/skills/ ├── workspaces/ │ ├── backend/ │ │ └── AGENTS.md -> ~/dev/kubeflow-notebooks-ai-rules/agents/backend/AGENTS.md │ ├── controller/ │ │ └── AGENTS.md -> .../agents/controller/AGENTS.md │ └── frontend/ │ ├── AGENTS.md -> .../agents/frontend/AGENTS.md │ └── src/__tests__/cypress/ │ └── AGENTS.md -> .../agents/frontend/cypress/AGENTS.md └── CLAUDE.md -> ~/dev/kubeflow-notebooks-ai-rules/agents/AGENTS.md

警告：这是最容易踩坑的地方。这些软链接文件本身不应该被提交到Kubeflow Notebooks的Git仓库中。因为它们指向的是你本地另一个独立的仓库路径。如果你提交了，其他克隆了Kubeflow Notebooks仓库的开发者，他们的路径不一致，软链接会失效。务必确保将**/AGENTS.md、CLAUDE.md、.agents/等添加到Kubeflow Notebooks仓库的.gitignore文件中。一个稳妥的做法是，在运行安装脚本后，立即检查并更新.gitignore。

3.3 验证与卸载

安装后，运行验证脚本是个好习惯：

./scripts/check.sh ~/dev/kubeflow-notebooks

这个脚本会检查所有预期的软链接是否存在且指向正确的位置。如果未来你移动了仓库位置或者软链接意外被删除，这个脚本能帮你快速发现问题。

当你需要切换分支，或者暂时不需要AI规则时，可以使用卸载脚本干净地移除所有软链接：

./scripts/uninstall.sh ~/dev/kubeflow-notebooks

卸载操作是安全的，它只删除软链接，不会触碰Kubeflow Notebooks仓库里的任何实际源代码文件。

4. 在主流AI工具中的实战应用

规则部署好了，接下来看如何在日常开发中与Claude Code和Cursor这两大主流AI编码助手配合，最大化其效用。

4.1 与Claude Code的无缝集成

Claude Code（或Cursor的Claude模型）对这类规则的支持非常“静默”且强大。一旦你在项目根目录放置了CLAUDE.md（它链向全局AGENTS.md），Claude在分析项目上下文时就会自动读取它。你不需要做任何特殊操作。

实战场景：当你打开workspaces/frontend/src/components/WorkspaceList.tsx文件，然后让Claude“添加一个排序功能”。Claude会：

1. 感知到你正在frontend目录下工作。
2. 自动加载并应用workspaces/frontend/AGENTS.md中的规则（例如，“状态变更必须使用useReducer或状态管理库，避免直接复杂useState嵌套”）。
3. 同时，它也会遵守根目录CLAUDE.md中的全局规则（例如，“所有新功能必须包含单元测试”）。
4. 最终，它生成的代码会自然地使用项目约定的状态管理方式，并可能在你完成组件后提醒你：“根据项目规范，需要为这个排序功能添加Jest和RTL测试。需要我帮你生成测试用例的骨架吗？”

这种集成是上下文感知的。如果你切换到workspaces/controller目录下的Go文件，Claude会自动切换到控制器相关的规则集。你几乎感觉不到规则文件的存在，但AI的输出质量却有了质的提升。

4.2 在Cursor中利用@引用进行精准控制

Cursor同样支持AGENTS.md，但它提供了更主动、更精准的控制方式：@引用。你可以在对话或编辑指令中，显式地告诉Cursor去参考哪个规则文件。

基础用法：假设你要修复一个后端API的Bug。

@AGENTS.md @workspaces/backend/AGENTS.md 请检查并修复 `/api/workspaces` 端点中关于用户权限验证的逻辑漏洞。

这条指令确保Cursor同时考虑了全局规则和后端专属规则。

高级用法：结合技能(SKILL)。这是发挥本项目威力的关键。假设你要实现一个前端API集成。

@AGENTS.md @workspaces/frontend/AGENTS.md @.agents/skills/kubeflow-notebooks-frontend-api-integration/SKILL.md 我需要为“工作空间模板”功能创建一个新的API集成。后端端点GET `/api/templates` 已经就绪，响应格式是 `{ data: Template[] }`。请遵循技能指南，完成前端部分的集成。

通过@引用技能文件，你直接将一个复杂任务的标准作业程序交给了AI。Cursor会严格按照SKILL.md里定义的步骤（定义类型、添加端点、创建客户端函数、在组件中使用）来生成代码，极大提高了输出的一致性和准确性。

4.3 编写AI友好的任务描述（Issue/PR描述）

要让AI发挥最大作用，你给它的“任务书”也必须写得好。项目给出了优秀的范例，其核心是提供充足的上下文和明确的验收标准。

一个反面例子：“优化工作空间列表页面。”——这对AI来说太模糊了。优化什么？性能？UI？功能？

一个AI友好的正面例子：

任务：为工作空间列表添加分页功能。 上下文： - 当前`/api/workspaces`接口支持`page`和`size`查询参数，返回格式为`{ items: Workspace[], total: number, page: number, size: number }`。 - 前端现有组件`WorkspaceListTable`一次性加载所有数据，在数据量超过50条时性能下降明显。 - 设计稿要求采用“上一页/下一页”和页码跳转的混合分页样式，每页默认显示20条。 验收标准： - [ ] 修改`useWorkspaces` Hook，支持接收`page`和`pageSize`参数，并返回分页元数据。 - [ ] 创建新的分页组件`PaginationControls`，包含页码显示、跳转和每页条数选择。 - [ ] 集成到`WorkspaceListTable`，确保翻页时表格数据平滑更新，不引起页面闪烁。 - [ ] 添加对应的单元测试，覆盖分页Hook和组件的基本交互。 - [ ] 更新相关的Cypress E2E测试，验证分页功能。

这样的描述，AI可以清晰地理解目标、现有条件、技术约束和完成标志，生成的代码方案会非常贴近实际需求，减少来回沟通的成本。这不仅是给AI看的，也是给人类 reviewer 看的优秀任务说明。

5. 利用AI进行高效的代码审查（PR Review）

本项目一个非常前瞻性的应用，是利用AI进行PR的初步审查。这并非要取代人工审查，而是作为第一道过滤器，自动化地检查那些常见的、可被规则化的代码规范问题，把人类reviewer的精力解放出来，去关注架构设计、业务逻辑等更核心的问题。

5.1 审查流程与提示词工程

项目提供了一个非常详细的Prompt模板。我们来拆解一下这个模板的精髓：

第一步：获取PR上下文。这是关键，AI不能只看代码差分。它需要理解这个PR要解决什么问题（链接的Issue），以及讨论中已经达成的共识（PR描述和评论）。这避免了AI提出一个已经在讨论中被否决的方案。

第二步：获取准确的代码差分。使用git diff upstream/notebooks-v2...HEAD（三重点号）非常重要。它比较的是目标分支（notebooks-v2）与当前分支最新提交的共同祖先之后的差异，这能给出最准确、最干净的变更集，避免了合并基选择错误带来的噪音。

第三步：加载相关规则。Prompt指示AI根据变更的文件路径，动态加载对应的AGENTS.md和SKILL.md。这确保了审查建议是基于具体模块的规范。

第四步：结构化输出问题。要求AI按文件、严重性、违反的规则、可粘贴的GitHub评论的格式输出。其中，“可粘贴的GitHub评论”要求用2-3句话直接说明问题和修复建议，且不能引用AGENTS.md文件本身（例如，不说“根据AGENTS.md第X条规则”，而直接说“函数缺少错误处理，建议添加try-catch”）。这产出的结果几乎可以直接用于PR评论，实用性极强。

5.2 人工复核与决策

必须清醒认识到，AI审查是辅助工具。它的优势在于不知疲倦地检查编码规范、简单的逻辑重复、拼写错误等。但它无法理解深层的业务逻辑合理性、架构演进的权衡、或者一些特定场景下的“特例”。

人工复核的重点应放在：

1. 业务逻辑正确性：AI生成的“优化建议”是否改变了代码的原始意图？
2. 架构一致性：建议的修改是否符合项目的整体架构方向？会不会引入不必要的复杂性？
3. 性能影响：AI建议的修改（如添加某个检查）是否会对性能产生负面影响？
4. 审查AI的建议本身：对于AI标记为“Blocking”的问题，要判断是否真的必须修改；对于“Recommendation”，要评估其价值。

一个高效的工作流是：在提交PR后，先运行一遍AI审查，自动生成初步评论。然后，人类reviewer快速浏览这些评论，确认无误后一键应用，再集中精力进行深度审查。这能显著提升审查效率和代码质量。

6. 扩展与定制：为你的团队打造专属AI助手

开源项目的规则是一个很好的起点，但每个团队或公司内部项目都有自己独特的“代码文化”和“历史包袱”。本项目良好的扩展性允许你为其添加自定义规则。

6.1 为新增模块创建AGENTS.md

假设Kubeflow Notebooks项目新增了一个notifications（通知）微服务，用Python编写。你需要为其创建AI指南。

1. 在AI规则仓库中创建文件：

   cd ~/dev/kubeflow-notebooks-ai-rules mkdir -p agents/notifications touch agents/notifications/AGENTS.md

2. 编写agents/notifications/AGENTS.md：

   # AI Guidelines for Notifications Service (Python) ## MUST / MUST NOT - MUST use FastAPI as the web framework. - MUST use Pydantic v2 for data validation and serialization. - MUST NOT use synchronous I/O operations in endpoint handlers (use `async def`). - MUST structure project according to `src/` layout. - MUST add type hints for all function signatures and public variables. ## Project Structure

   notifications/ ├── src/ │ ├── main.py # FastAPI app initialization │ ├── api/ # API routes │ ├── core/ # Configuration, security │ ├── models/ # Pydantic and SQLAlchemy models │ ├── schemas/ # Pydantic schemas for request/response │ └── services/ # Business logic └── tests/ # Pytest tests

   ## Common Patterns - Database sessions are injected via dependencies. Do not create them manually. - All external API calls must be wrapped in a circuit breaker using `backoff` library. - Logging must use the structured logger from `core.logging`.

3. 更新映射配置：编辑agents/mappings.conf，添加一行，将新规则文件映射到Kubeflow Notebooks仓库的实际路径。

   agents/notifications/AGENTS.md:notifications/AGENTS.md

4. 重新运行安装脚本：在Kubeflow Notebooks目录下，规则就会生效。

6.2 创建针对性的SKILL.md技能

当某个任务模式反复出现时，就值得将其抽离为技能。例如，团队发现大家写FastAPI的CRUD端点时风格不一，可以创建一个技能。

1. 创建技能目录和文件：

   mkdir -p skills/kubeflow-notebooks-python-crud-endpoint touch skills/kubeflow-notebooks-python-crud-endpoint/SKILL.md

2. 编写SKILL.md：

   # Skill: Authoring a Standard CRUD Endpoint in FastAPI ## When to use this skill When you need to create a new set of Create, Read, Update, Delete endpoints for a domain model. ## Inputs needed from the user - The name of the domain model (e.g., `Notification`). - The fields of the Pydantic schema for creation (`CreateSchema`) and response (`ResponseSchema`). ## Step-by-step workflow 1. **Define Schemas**: In `schemas/notification.py`, define `NotificationCreate`, `NotificationUpdate`, and `NotificationResponse` using Pydantic. 2. **Create Router**: In `api/endpoints/notifications.py`, create a FastAPI `APIRouter`. 3. **Implement Endpoints**: - `POST /`: Create item. Use `@router.post("/", response_model=NotificationResponse, status_code=201)`. - `GET /{id}`: Get item by ID. Include proper 404 error handling. - `GET /`: List items with optional pagination (`skip`, `limit`). - `PUT /{id}`: Full update. - `DELETE /{id}`: Delete item. 4. **Inject Service**: All endpoint functions should call methods from a `NotificationService` class in the `services/` layer. 5. **Add Tests**: In `tests/api/`, add integration tests for each endpoint. ## Example prompt for AI "Using the Python CRUD endpoint skill, create endpoints for a `Subscription` model with fields `user_id` (str) and `is_active` (bool)."

3. 技能会自动被链接：下次运行install.sh时，这个新技能会被自动软链接到.agents/skills/目录下，供所有AI工具调用。

通过这种方式，你可以不断沉淀团队的最佳实践，将隐性的知识显性化、标准化，让每一位团队成员（包括AI助手）都能快速达到同样的高水平产出。