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 CommitsPR描述必须包含清晰的上下文和验收标准。通用开发守则代码必须通过所有静态检查如ESLint、gofmt、golangci-lint新增功能必须包含测试等。而在agents/backend/、agents/frontend/等子目录下的AGENTS.md文件则是针对特定技术栈的“部门规章”。它们继承并细化了全局规则。例如agents/frontend/AGENTS.md会详细规定组件设计React组件必须使用TypeScript优先使用函数组件Props必须定义明确的接口。状态管理全局状态使用Redux Toolkit还是React Context如何划分sliceAPI交互必须使用项目封装的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状态。”为什么这么设计降低提示词长度AI处理长上下文有成本和性能限制。如果把所有技能细节都塞进AGENTS.md文件会变得极其臃肿。通过技能解耦AI在需要执行特定任务时才去动态加载对应的SKILL.md保证了核心策略文件AGENTS.md的简洁和高效加载。提升可维护性当某个任务的工作流需要更新时比如API响应格式变了你只需要修改对应的SKILL.md而无需触碰稳定的AGENTS.md策略文件。符合开放标准项目遵循了agentskills.io的规范将技能文件统一软链接到.agents/skills/目录下。这意味着未来任何支持该标准的AI工具都能自动发现和利用这些技能具备了很好的工具兼容性和可移植性。注意在编写SKILL.md时要确保它们是原子化的、可独立执行的。一份好的技能文档应该像一份优秀的菜谱有明确的输入、清晰的步骤、和预期的输出。3. 实战部署与集成指南理解了设计理念下一步就是把它用起来。部署过程不复杂但有几个关键细节需要特别注意否则可能会遇到软链接失效或意外提交的问题。3.1 环境准备与仓库克隆首先你需要一个正确的工作目录结构。假设你的开发根目录是~/dev操作如下# 1. 进入你的开发目录 cd ~/dev # 2. 克隆AI规则仓库 git clone gitgithub.com:caponetto/kubeflow-notebooks-ai-rules.git # 3. 克隆Kubeflow Notebooks仓库注意指定notebooks-v2分支 # 如果你有项目fork将 kubeflow 替换为你的GitHub用户名 git clone -b notebooks-v2 gitgithub.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脚本做了以下几件重要的事理解它们有助于排查问题读取映射配置脚本首先会读取agents/mappings.conf文件。这个文件定义了源文件在AI规则仓库内和目标软链接路径在Kubeflow Notebooks仓库内的对应关系。例如它可能指定将agents/frontend/AGENTS.md软链接到kubeflow-notebooks/workspaces/frontend/AGENTS.md。创建目录软链接对于skills/目录下的每个技能脚本会在Kubeflow Notebooks仓库的根目录创建.agents/skills/目录如果不存在并为每个技能创建软链接。这是遵循agentskills.io标准让AI工具能自动扫描发现技能。创建文件软链接根据mappings.conf在各个模块目录下创建AGENTS.md和CLAUDE.md的软链接。处理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.mdClaude在分析项目上下文时就会自动读取它。你不需要做任何特殊操作。实战场景当你打开workspaces/frontend/src/components/WorkspaceList.tsx文件然后让Claude“添加一个排序功能”。Claude会感知到你正在frontend目录下工作。自动加载并应用workspaces/frontend/AGENTS.md中的规则例如“状态变更必须使用useReducer或状态管理库避免直接复杂useState嵌套”。同时它也会遵守根目录CLAUDE.md中的全局规则例如“所有新功能必须包含单元测试”。最终它生成的代码会自然地使用项目约定的状态管理方式并可能在你完成组件后提醒你“根据项目规范需要为这个排序功能添加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审查是辅助工具。它的优势在于不知疲倦地检查编码规范、简单的逻辑重复、拼写错误等。但它无法理解深层的业务逻辑合理性、架构演进的权衡、或者一些特定场景下的“特例”。人工复核的重点应放在业务逻辑正确性AI生成的“优化建议”是否改变了代码的原始意图架构一致性建议的修改是否符合项目的整体架构方向会不会引入不必要的复杂性性能影响AI建议的修改如添加某个检查是否会对性能产生负面影响审查AI的建议本身对于AI标记为“Blocking”的问题要判断是否真的必须修改对于“Recommendation”要评估其价值。一个高效的工作流是在提交PR后先运行一遍AI审查自动生成初步评论。然后人类reviewer快速浏览这些评论确认无误后一键应用再集中精力进行深度审查。这能显著提升审查效率和代码质量。6. 扩展与定制为你的团队打造专属AI助手开源项目的规则是一个很好的起点但每个团队或公司内部项目都有自己独特的“代码文化”和“历史包袱”。本项目良好的扩展性允许你为其添加自定义规则。6.1 为新增模块创建AGENTS.md假设Kubeflow Notebooks项目新增了一个notifications通知微服务用Python编写。你需要为其创建AI指南。在AI规则仓库中创建文件cd ~/dev/kubeflow-notebooks-ai-rules mkdir -p agents/notifications touch agents/notifications/AGENTS.md编写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 Structurenotifications/ ├── 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.更新映射配置编辑agents/mappings.conf添加一行将新规则文件映射到Kubeflow Notebooks仓库的实际路径。agents/notifications/AGENTS.md:notifications/AGENTS.md重新运行安装脚本在Kubeflow Notebooks目录下规则就会生效。6.2 创建针对性的SKILL.md技能当某个任务模式反复出现时就值得将其抽离为技能。例如团队发现大家写FastAPI的CRUD端点时风格不一可以创建一个技能。创建技能目录和文件mkdir -p skills/kubeflow-notebooks-python-crud-endpoint touch skills/kubeflow-notebooks-python-crud-endpoint/SKILL.md编写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_modelNotificationResponse, status_code201). - 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).技能会自动被链接下次运行install.sh时这个新技能会被自动软链接到.agents/skills/目录下供所有AI工具调用。通过这种方式你可以不断沉淀团队的最佳实践将隐性的知识显性化、标准化让每一位团队成员包括AI助手都能快速达到同样的高水平产出。