1. 项目概述DotAI Boiler一个为AI辅助编程而生的“第二大脑”如果你和我一样每天都在和Cursor、GitHub Copilot、Claude这些AI编程助手打交道那你肯定也经历过这种“断片”时刻昨天和AI助手花了半小时讨论好的项目架构细节今天打开新会话它忘得一干二净你又得从头解释一遍。或者团队里不同成员用AI生成的代码风格迥异一个项目里能找出三种不同的错误处理模式后期的维护成本直线上升。DotAI Boiler这个由开发者helloprkr开源的框架就是为了解决这些痛点而生的。它不是一个简单的代码生成器而是一个结构化的知识生态系统专门为AI辅助的开发工作流程设计。你可以把它理解为你项目的“第二大脑”或“AI领航员”。它的核心目标是在你和AI助手之间建立一个持久、可演进、标准化的上下文桥梁确保AI不仅能理解你当前的指令还能记住项目的完整历史、架构决策、踩过的坑以及团队的最佳实践。简单来说它通过一套精密的目录结构和规则文件.ai/目录将原本分散在聊天记录、临时笔记和开发者脑海中的“项目智慧”固化下来。无论是技术选型蓝图Blueprints、可复用的代码片段Snippets、记录学习与错误的法典Codex还是管理单次任务上下文的会话SessionDotAI Boiler都提供了标准化的容器。这极大地降低了在复杂项目中与AI协作的认知负荷让AI从一个“健忘的天才实习生”转变为一个“有记忆、守规矩的资深搭档”。2. 核心架构与设计哲学为什么是“Boiler”“Boiler”直译是锅炉但在软件开发中它常指“Boilerplate Code”即那些重复性高、模式固定的样板代码。DotAI Boiler的命名非常贴切它要解决的正是AI辅助开发中那些“重复造轮子”和“上下文丢失”的样板问题。它的设计哲学可以概括为三点结构化、可演进、标准化。2.1 目录结构深度解析一切皆文件项目的核心是根目录下的.ai文件夹。这个设计非常巧妙它利用了当前主流AI助手如Cursor能够读取并理解项目根目录下特定文件的能力。整个框架的威力就藏在这个目录树里。我们来拆解几个最关键的部分codex/法典这是项目的长期记忆中枢。它不仅仅是一个错误日志更是一个经验知识库。你可以把每次解决一个棘手Bug的思路、对某个库性能优化的心得、或者验证过的设计模式记录在这里。AI在后续会话中可以通过引用这些文件快速获得“历史经验”避免重蹈覆辙。例如一个learn-react-optimization.md文件里可能记录了如何用React.memo和useMemo精准优化组件渲染避免全量重绘的实战案例。session/会话这是项目的短期工作记忆。当你开始一项新功能比如“实现用户认证系统”时你应该在这里创建一个auth-implementation.md文件。这个文件会像会议纪要一样逐步记录下需求定义、技术方案讨论、数据库Schema设计、API接口规划、遇到的阻塞问题及解决方案。这个文件是动态更新的你或AI在开发过程中任何新的决策和发现都应该追加进去。下次你或另一位团队成员或AI需要继续这项工作时只需“导入”这个会话文件就能立刻恢复到上次的工作上下文无缝衔接。blueprints/蓝图这是预设的、最佳实践的架构实施方案。比如supabase-drizzle蓝图它可能包含了一整套从初始化Supabase项目、配置Drizzle ORM、编写类型安全的Server Actions到部署上线的分步指南。蓝图的价值在于提供经过验证的、一致的技术栈集成方案确保团队不同成员、不同时期创建的同类型服务都遵循相同的模式和标准极大减少了技术债。rules/规则这是指导AI行为的“宪法”特别是通过Model Context Protocol (MCP)格式定义的规则。MCP可以理解为给AI助手看的“编程规范”或“模式提示”。例如一个针对Go语言的MCP规则会明确告诉AI“在本项目中错误处理请统一使用if err ! nil { return fmt.Errorf(\context: %w\, err) }这种包装模式”。这确保了AI生成的代码符合项目既定规范而不是随意发挥。2.2 与AI助手的工作流集成DotAI Boiler本身不运行AI模型它是一个增强AI助手能力的框架。它的使用高度依赖你所用的编辑器或工具。以目前集成度最高的Cursor编辑器为例上下文注入你可以在Cursor的Chat界面中通过引用.ai/目录下的文件。例如输入“import .ai/session/auth-implementation.md”AI助手就会将整个会话文件的内容作为上下文加载进来它便知晓之前所有的讨论和决策。规则生效放置在.cursor/rules/目录下的MCP文件会被Cursor编辑器自动识别和应用。当AI在编写Go代码时对应的go.mcp规则会潜移默化地影响其代码生成风格。主动查询在需要时你可以直接指示AI“参考我们codex里关于数据库连接池优化的记录”AI会去读取对应的codex文件并应用其中的知识。这种设计使得框架本身轻量、无侵入只是通过文件系统来组织和呈现知识与任何支持文件读取的AI工具都能良好协作。3. 核心模块实操详解从零搭建你的AI开发工作流理解了设计理念我们来动手实操看看如何在一个真实项目中部署和使用DotAI Boiler。假设我们正在启动一个名为“NextMart”的Next.js全栈电商项目。3.1 初始化与基础配置首先我们需要将DotAI Boiler的结构引入到我们的项目中。# 1. 克隆样板库作为参考而非直接作为项目 git clone https://github.com/helloprkr/dotai_boiler.git ~/dotai-boiler-reference # 2. 进入你的真实项目目录 cd ~/projects/nextmart # 3. 关键步骤复制.ai框架目录到你的项目根目录 cp -r ~/dotai-boiler-reference/.ai ./ # 4. 可选但推荐初始化核心的文档文件 cp ~/dotai-boiler-reference/.ai/codex/learn.md ./.ai/codex/learn-demo.md cp ~/dotai-boiler-reference/.ai/session/template.md ./.ai/session/注意这里不建议使用Git Submodule因为.ai目录下的内容如session, codex是高度项目特定的需要频繁修改。将其作为普通目录拷贝进来更方便进行版本控制你可以将整个.ai目录纳入你的项目Git仓库。接下来你需要根据项目技术栈启用或创建对应的蓝图和规则。比如我们用了Next.js 15App Router、TypeScript、Tailwind CSS和Prisma。# 查看是否有现成的Next.js蓝图 ls -la ./.ai/blueprints/ | grep -i next # 假设没有完全匹配的我们可以基于一个最接近的蓝图如nextjs-complete进行复制和修改 cp -r ./.ai/blueprints/nextjs-complete ./.ai/blueprints/nextmart-stack # 然后编辑 ./.ai/blueprints/nextmart-stack/README.md将其内容修改为我们项目的具体技术选型和理由。3.2 会话管理实战开发一个“用户个人中心”功能现在产品经理提了一个需求“开发用户个人中心页面包含资料展示和编辑功能”。我们开始一个会话。创建会话文件cd ~/projects/nextmart touch ./.ai/session/2024-05-27-user-profile.md初始化会话内容用编辑器打开该文件填入初始上下文。不要写成长篇需求文档而是用对话和要点格式方便AI理解。# 会话用户个人中心功能开发 **开始时间**2024-05-27 **相关方**前端我后端AI助手模拟 **目标**在NextMart项目中实现用户个人中心页面。 ## 1. 功能范围 - 页面路由/app/dashboard/profile - 功能模块 1. 信息展示头像、昵称、邮箱、注册时间。 2. 信息编辑可编辑昵称、头像上传至S3/Cloudinary。 3. 安全设置预留入口本期不实现。 ## 2. 技术栈与约束 - 框架Next.js 15 (App Router) - 样式Tailwind CSS - 状态管理React Server Components useState for client interactivity - 数据获取直接在同路由的page.tsx或layout.tsx中使用async/await调用数据库。 - ORMPrisma已配置模型见prisma/schema.prisma中的User模型。 - 文件上传计划使用uploadthing/next但需要评估。有替代方案吗 ## 3. 待决策问题 - Q1: 头像上传是使用客户端直接上传到第三方如UploadThing还是通过我们自己的API代理 - Q2: 昵称编辑是采用内联编辑Inline Edit还是跳转至独立编辑页 - Q3: 是否需要为这个页面添加服务端缓存策略 ## 4. 当前进展 - [ ] 页面基础结构搭建 - [ ] 数据获取逻辑实现 - [ ] 信息展示组件开发 - [ ] 编辑功能实现这个文件就是你与AI助手的“共享白板”。与AI协作打开Cursor在Chat中首先导入会话上下文import ./.ai/session/2024-05-27-user-profile.md然后基于这个上下文提问“根据以上会话请帮我创建/app/dashboard/profile/page.tsx的初始组件结构包含从数据库获取用户信息的逻辑。请使用Prisma。”AI生成的代码会基于你提供的完整上下文更精准。生成代码后你可以将关键的实现决策比如你决定采用内联编辑和UploadThing方案追加到会话文件中。更新会话## 4. 当前进展 - [x] 页面基础结构搭建已由AI生成基础RSC页面使用await prisma.user.findUnique获取数据。 - [x] 数据获取逻辑实现已完成。 - [ ] 信息展示组件开发 - [ ] 编辑功能实现 ## 5. 关键决策记录 (2024-05-27更新) - A1: 采用uploadthing/next进行客户端直传因为它支持App Router且免服务器逻辑。已在项目中安装。 - A2: 采用内联编辑模式使用useState和debounce优化体验。已创建EditableField组件。 - A3: 页面数据更新不频繁决定在page.tsx中使用export const revalidate 3600进行ISR每小时重新验证。这样这个会话文件就成了这个功能开发的完整溯源日志。3.3 法典系统实战将经验转化为团队资产在开发“个人中心”时你遇到了一个坑直接在前端组件中导入prisma客户端导致了“PrismaClient实例化过多”的警告。你研究后发现在Next.js Server Component中需要用一个全局单例模式来管理PrismaClient。这个解决问题的过程就是值得录入法典的知识。创建法典条目touch ./.ai/codex/learn-prisma-nextjs-singleton.md编写法典内容格式建议# 学习在Next.js App Router中正确初始化PrismaClient **关键词**Next.js, App Router, Prisma, 单例模式, 热重载 **关联问题**开发/dashboard/profile页面时控制台出现“警告已有10个PrismaClient实例被实例化”。 **根本原因**Next.js开发环境下的热重载Fast Refresh会导致模块重新执行如果直接在组件中new PrismaClient()每次重载都会创建新实例可能耗尽数据库连接。 **解决方案** 在lib/prisma.ts中创建并导出一个全局单例 typescript import { PrismaClient } from prisma/client const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined } export const prisma globalForPrisma.prisma ?? new PrismaClient() if (process.env.NODE_ENV ! production) globalForPrisma.prisma prisma使用方式在所有Server Component、Server Action或API Route中从/lib/prisma导入这个prisma实例而不是直接new PrismaClient()。验证结果应用此模式后警告消失数据库连接数稳定。参考链接 Prisma官方文档 - Next.js这个法典条目不仅记录了问题和方案还解释了原理并给出了可直接复用的代码。未来任何团队成员或AI在Next.js项目中遇到Prisma连接问题搜索codex就能立刻找到答案。3.4 蓝图与片段应用保证代码一致性假设我们的项目决定统一使用一种特定的API响应格式和错误处理方式。我们可以通过蓝图和片段来固化这个模式。创建自定义片段在.ai/snippets/typescript/下创建api-response.ts。// .ai/snippets/typescript/api-response.ts /** * 标准API响应格式 * template T 成功时返回的数据类型 */ export type ApiResponseT any | { success: true; data: T; message?: string; } | { success: false; error: { code: string; message: string; details?: unknown; }; }; /** * 创建成功响应 */ export function createSuccessResponseT(data: T, message?: string): ApiResponseT { return { success: true, data, message }; } /** * 创建错误响应 */ export function createErrorResponse(code: string, message: string, details?: unknown): ApiResponse { return { success: false, error: { code, message, details } }; }在蓝图中引用在相关的后端服务蓝图中例如.ai/blueprints/nextmart-stack/api-design.md明确写道“所有API路由必须使用/ai/snippets/typescript/api-response.ts中定义的ApiResponse类型作为返回格式。”通过MCP规则强化在.ai/rules/typescript/api.mcp中定义规则。rule api_response_format { context: when writing an API route handler in Next.js App Router, pattern: export async function GET/POST/PUT/DELETE(...): PromiseApiResponse... { ... }, explanation: All API responses must use the standardized ApiResponse type from our snippets for consistency. }当AI在编写API路由时这条规则会提示它使用统一的响应格式。4. 高级特性与定制化让框架为你所用4.1 Model Context Protocol规则精讲MCP规则是控制AI输出的“细粒度旋钮”。一个有效的MCP规则包含几个部分rule [name]: 规则名称。context: 规则生效的上下文描述越具体越好。pattern: 期望的代码模式或行为模式可以是代码片段也可以是自然语言描述。explanation: 为什么需要这个规则帮助AI理解其重要性。实战案例禁止在React组件中直接使用index作为key。 在.ai/rules/react/performance.mcp中添加rule react_key_anti_pattern { context: when mapping over an array to create React elements, pattern: avoid using key{index} unless the list is static and never reordered, alternative: Use a stable unique ID from the data item, e.g., key{item.id}, explanation: Using array index as key can cause performance issues and bugs when the list items are reordered, filtered, or items are added/removed. It breaks Reacts reconciliation algorithm. }这样当AI生成列表渲染代码时会倾向于寻找数据中的唯一标识而不是简单地使用index。4.2 插件系统与外部工具集成DotAI Boiler预留了plugins/目录用于集成更强大的外部AI工具。例如集成v0.dev在.ai/plugins/v0/下创建配置文件存放你的API密钥注意安全使用环境变量。创建一个脚本generate-component.sh接收自然语言描述调用v0的API并将生成的组件代码保存到指定位置同时自动在codex中记录一次生成记录。这样你可以通过一条命令如npm run ai:generate -- --component 一个带有搜索框和用户头像的导航栏快速生成UI原型极大提升前端开发效率。5. 常见问题、排查技巧与避坑指南在实际使用DotAI Boiler的几个月里我积累了一些宝贵的经验和教训这里分享给你希望能帮你少走弯路。5.1 会话文件变得臃肿怎么办问题一个功能复杂的会话文件可能很快增长到几百行导致AI加载上下文变慢且难以找到关键信息。解决方案采用“分层会话”策略。主会话文件(session/feature-a.md): 只保留最高层的目标、核心决策、当前阻塞问题和进度概览。像一个目录。子任务文件(session/feature-a-subtask-1.md,...-2.md): 将具体的技术讨论、代码片段、错误排查细节拆分成独立的子文件。在主会话中通过链接引用子任务文件。例如“关于身份验证JWT策略的详细讨论见subtasks/auth-jwt.md”。这样AI在需要深入了解某个子问题时你可以指示它去读取特定子文件而不是一次性加载所有内容。5.2 AI助手不遵守MCP规则问题明明定义了规则但AI生成的代码还是不符合预期。排查步骤检查规则位置确认MCP文件放在了正确的位置。对于Cursor是放在.cursor/rules/下还是.ai/rules/下并被正确引用需要查看Cursor的官方文档确认其加载规则文件的路径。检查规则语法MCP虽然不是严格编程语言但格式错误可能导致解析失败。确保rule、context、pattern等关键词书写正确。规则描述是否清晰context描述是否足够精确地匹配了你的编码场景pattern是展示了正确的代码样例还是仅仅描述了错误行为提供正面样例应该怎么做通常比描述反面样例不要怎么做更有效。规则冲突是否存在多条规则定义了相同或相似的context导致AI混淆检查并简化规则。手动提示在Chat中可以明确提醒AI“请遵循我们项目中关于API响应格式的MCP规则规则ID:api_response_format。” 这是一种强化的方式。5.3 如何让法典的价值最大化误区把法典当成一个普通的笔记文件夹随意记录。最佳实践即时记录一旦解决一个非显而易见的问题或学到一项可复用的技术立刻花5分钟写成法典条目。拖延会导致细节遗忘。结构化模板为不同类型的知识设计模板。比如“错误排查”模板问题现象、环境、排查步骤、根本原因、解决方案、“性能优化”模板优化前指标、优化手段、优化后指标、原理分析、“设计决策”模板备选方案、权衡利弊、最终选择理由。主动引用在代码审查、技术讨论或新成员入职时养成习惯说“关于这个问题我们在codex里有一个记录可以参考learn-xxx.md。” 鼓励团队查询和使用法典。定期回顾与清理每个季度可以组织一次“法典维护会”回顾旧条目将过时的技术栈条目归档将零散的相关条目合并成一篇更全面的指南。保持法典的鲜活和精炼。5.4 在团队中推广的挑战挑战团队成员习惯不同有人喜欢用有人觉得是负担。破局点自上而下示范技术负责人或架构师率先在核心、复杂的模块开发中使用DotAI Boiler并展示其带来的好处如减少重复解释、加速新人上手、决策可追溯。降低启动成本为新项目准备好一套预配置的、包含团队通用技术栈蓝图的.ai目录模板。新项目一键初始化大家就在同一个起跑线上。积分制鼓励在团队内部可以设立简单的奖励机制比如“月度最佳法典条目”评选奖励那些写了高质量、被频繁引用的法典的成员。不追求100%接受它作为一个“增强工具”而非“强制流程”。即使只有50%的关键决策和复杂问题被记录在案对团队的知识沉淀也是巨大的提升。从我个人的使用体验来看DotAI Boiler带来的最大改变是让AI辅助编程从一种“随机的、一次性的魔法”变成了一种“可预测的、可持续的工程实践”。它迫使你和你的团队更结构化地思考问题、更规范地编写代码、更有意识地积累知识。初期投入一点时间搭建和适应这套体系长期来看它在降低沟通成本、提升代码质量、加速团队成长方面的回报是绝对超值的。