1. 项目概述AI 驱动的结构化开发工具箱如果你和我一样日常开发中重度依赖 Claude Code、Cursor 或 GitHub Copilot 这类 AI 编程助手那你肯定也经历过这种场景每次开启一个新项目都得花上半小时甚至更久在聊天框里反复向 AI 描述你的技术栈偏好、项目结构规范、代码风格要求。比如“后端用 FastAPIORM 用 SQLAlchemy 2.0响应模型统一用 Pydantic v2”“前端用 Next.js 14 App Router状态管理用 Zustand请求库用 TanStack Query”。说一遍还行但每个新项目都重复一遍不仅效率低下而且 AI 的理解还可能出现偏差导致生成的代码风格前后不一。Lu7474/ai-coding-toolkit 这个项目就是为了根治这个痛点而生的。它不是什么复杂的框架而是一套精心设计的“元工具”——一套用于生成代码的模板和规则文件。其核心思想极其简单却非常有效将你与 AI 协作的“上下文”和“规范”固化下来。通过一个结构化的项目规格说明书PROJECT_SPEC.md和一系列针对特定技术栈的规则文件Rules你可以在项目启动的瞬间就将你所有的开发习惯、架构选择和最佳实践“注入”给 AI 助手。这样一来AI 从第一行代码开始就按照你的思维模式和团队规范来工作大幅提升从想法到可运行代码的流转速度与一致性。这套工具包尤其适合全栈开发者、独立开发者或小型敏捷团队。无论你是要快速验证一个产品创意构建一个内部工具还是启动一个标准的 Web 应用它都能帮你省去大量重复性的项目初始化与规范沟通工作。它的价值不在于替代你的思考而在于将你的思考成果模板化、自动化让你和 AI 的协作真正进入“心流”状态。2. 工具箱核心组件深度解析2.1 PROJECT_SPEC.md从模糊想法到清晰蓝图这是整个工具箱的“大脑”和起点。它不是一个简单的文件清单而是一个引导你系统性思考项目定义的交互式问卷。其设计哲学是模糊的需求无法产生精确的代码。AI 再强大如果给它的指令是“帮我建个博客系统”它产生的方案可能千差万别。而 PROJECT_SPEC.md 通过一系列结构化问题强迫你或产品经理在编码之前先想清楚最关键的问题。我仔细研究了其内容它通常涵盖以下几个核心模块项目元信息项目名称、简短描述、核心价值主张。这帮助 AI 理解项目的“灵魂”。功能范围以用户故事User Story或功能列表的形式定义 MVP最小可行产品和未来迭代的功能。例如“作为访客我可以浏览公开的文章列表”就是一个清晰的用户故事。技术栈选型这是规则文件发挥作用的基础。你需要明确指定后端框架如 FastAPI、前端框架如 Next.js、数据库如 PostgreSQL、ORM、认证方式等。AI 会根据这里的选型调用对应的 BACKEND_RULES.md 或 FRONTEND_RULES.md。数据模型初步的核心实体与关系定义。不需要完整的 SQL但需要描述如“User”、“Post”、“Comment”以及它们之间的关系一对多、多对多。这为 AI 生成 SQLAlchemy 模型或 Prisma Schema 提供了依据。API 设计规划主要的 RESTful 端点或 GraphQL 查询/变更。例如GET /api/posts,POST /api/auth/login。部署与运维目标部署环境如 Docker 容器部署在云服务器、CI/CD 偏好、环境变量管理策略。这部分链接到 DEPLOY_RULES.md。实操心得填写这个文件的过程本身就是一次极佳的需求梳理。我建议即使不用 AI在启动任何新项目前也尝试回答一遍这些问题。你会发现很多边缘情况在编码前就被提前发现了。对于 AI 来说这份文件就是它的“产品需求文档”和“技术方案设计书”质量直接决定生成代码的贴合度。2.2 VIBECODING_WORKFLOW.md定义人机协作的节奏这是工具箱的“方法论”或“作战手册”。它定义了如何将 PROJECT_SPEC.md 与各个 RULES 文件在开发流程中串联使用。一个好的工作流能避免混乱让 AI 辅助变得有序可预测。典型的 “Vibecoding” 工作流可能包含以下阶段研究与规划基于填写好的 SPEC让 AI 生成一份初步的项目实施计划包括目录结构、阶段划分、依赖库列表。数据层先行优先创建数据库模型和迁移脚本。将 BACKEND_RULES.md 中关于 SQLAlchemy 的规范如时间戳混入、软删除模式提供给 AI生成符合规范的 Model 类。API 骨架搭建根据 SPEC 中的 API 设计生成 FastAPI 的路由器、Pydantic 请求/响应模型。此时 BACKEND_RULES.md 中关于依赖注入、错误处理、响应封装的规则至关重要。业务逻辑填充在坚实的架构上逐步实现每个端点的核心逻辑。AI 在此阶段可以辅助编写具体的服务层和工具函数。前端界面对接当后端 API 可用后切换到前端。将 FRONTEND_RULES.md 提供给 AI生成符合规范的 React 组件、TypeScript 接口和 TanStack Query 的 hooks。集成与部署最后利用 DEPLOY_RULES.md 生成 Dockerfile、docker-compose.yml、Nginx 配置和 CI/CD 流水线脚本。注意事项这个工作流不是僵化的。你可以根据项目实际情况调整顺序。例如对于原型验证你可能希望 AI 先快速生成一个包含前端界面的全功能单体应用之后再重构和解耦。关键是要让 AI 和你自己都明确当前处于哪个阶段该使用哪部分上下文。2.3 RULES 文件集你的团队编码宪法这是工具箱的“肌肉记忆”。如果说 SPEC 定义了“做什么”那么 RULES 文件就定义了“怎么做”以及“做成什么样”。它们是针对特定技术栈的、极其详尽的编码规范和最佳实践集合。BACKEND_RULES.md以 Python 后端为例它可能规定项目结构严格的src/布局models/,schemas/,api/,core/,services/等目录的职责。代码风格使用isort和black进行格式化类型提示必须完整。FastAPI 特定规则所有路由必须包含tags依赖项使用Depends且可测试全局异常处理器格式统一。SQLAlchemy 规范使用声明式映射模型继承一个包含id、created_at、updated_at的Base类关系定义使用特定的懒加载策略。Pydantic 规范区分用于数据库的Model和用于 API 的SchemaConfig类的统一设置。日志与监控统一使用structlog进行结构化日志记录日志级别和格式有明确要求。安全规范密码哈希使用passlib的特定算法JWT 令牌的生成与验证流程标准化。FRONTEND_RULES.md以 Next.js TypeScript 前端为例它可能规定项目结构App Router 下的app/,components/,lib/,types/组织方式。组件规范所有组件必须是函数式组件使用React.FC或更推荐的方式定义 Props 类型。UI 组件使用Tailwind CSS进行样式化且遵循一套设计令牌颜色、间距。状态与数据获取服务端状态使用TanStack Query客户端状态使用Zustand。定义统一的apiClient封装fetch包含请求拦截、错误处理和基础 URL 配置。TypeScript 规范禁止使用any类型接口和类型定义必须放在types/目录下。DEPLOY_RULES.md它定义了从代码到服务的最后一公里标准。容器化多阶段构建的 Dockerfile 模板优化镜像层和体积。服务编排docker-compose.yml模板包含数据库、后端、前端服务以及可能的 Redis 等依赖。Web 服务器Nginx 配置模板处理静态文件、SSL/TLS 终止和反向代理到后端。CI/CDGitHub Actions 或 GitLab CI 的流水线示例包括测试、构建、推送镜像和部署步骤。运维检查项环境变量清单、备份策略、健康检查端点设计。核心价值这些规则文件将你个人或团队长期积累的、散落在各处的“知识”和“坑点”系统化、文档化。AI 在生成每一行代码时都受到这些规则的约束从而保证输出的一致性、安全性和可维护性。这相当于为 AI 配备了一位永不疲倦的资深架构师进行代码审查。3. 实战演练从零启动一个博客系统让我们通过一个具体的例子——构建一个简单的个人博客系统来演示如何将这套工具箱用起来。假设我们使用其预设的推荐技术栈FastAPI PostgreSQL Next.js。3.1 第一步定义项目规格在项目根目录创建PROJECT_SPEC.md或从模板复制并开始填写# 项目规格说明书SimpleBlog ## 1. 项目概述 - **名称**SimpleBlog - **描述**一个极简的个人博客系统支持文章发布、分类和公开浏览。 - **核心价值**让作者能专注于写作读者能获得纯净的阅读体验。 ## 2. 功能范围 **MVP 功能** - 访客可以浏览所有公开文章列表分页。 - 访客可以点击阅读单篇文章详情。 - 作者可以通过管理后台登录。 - 作者可以创建、编辑、删除文章草稿/发布状态。 - 文章支持分类标签管理。 **未来功能** - 文章评论功能。 - 全文搜索。 - RSS 订阅。 ## 3. 技术栈 - **后端**Python FastAPI - **数据库**PostgreSQL - **ORM**SQLAlchemy 2.0 Alembic迁移 - **数据验证**Pydantic v2 - **认证**JWTJSON Web Tokens - **前端**Next.js 14 (App Router) TypeScript - **样式**Tailwind CSS - **状态与数据获取**TanStack Query (React Query) Axios - **部署**Docker Docker Compose部署到云服务器如 Ubuntu ## 4. 数据模型初步 - **User**id, username(唯一), hashed_password, email, is_active, created_at - **Post**id, title, slug(唯一), content, summary, status(草稿/发布), published_at, author_id(外键关联 User), created_at, updated_at - **Category**id, name, slug - **关联表**PostCategory多对多关系关联 Post 和 Category ## 5. API 设计主要端点 - POST /api/auth/login - 作者登录返回 JWT - GET /api/posts - 获取文章列表支持分页、按分类筛选 - GET /api/posts/{slug} - 根据 slug 获取单篇文章 - POST /api/posts - 创建新文章需认证 - PUT /api/posts/{id} - 更新文章需认证 - DELETE /api/posts/{id} - 删除文章需认证 - GET /api/categories - 获取所有分类 ## 6. 部署 - 使用 Docker Compose 定义服务postgres, backend, frontend。 - 后端和前端分别构建为 Docker 镜像。 - 通过 Nginx 反向代理前端处理静态资源并代理 API 请求到后端。 - 使用 Let‘s Encrypt 配置 HTTPS。3.2 第二步与 AI 协作生成项目骨架打开你的 AI 助手如 Cursor将整个PROJECT_SPEC.md的内容粘贴进去并附上指令“请基于以上项目规格说明书为我生成这个 SimpleBlog 项目的详细实施计划包括推荐的目录结构、需要安装的核心依赖包列表以及第一阶段数据层和核心 API的开发任务分解。”AI 会根据 SPEC 生成一份计划。你审核并确认后就可以开始分步执行。首先创建数据模型。在聊天中除了 SPEC现在附加BACKEND_RULES.md文件作为上下文。然后给 AI 指令“请根据 PROJECT_SPEC.md 中定义的数据模型遵循 BACKEND_RULES.md 中的规范使用 SQLAlchemy 2.0 的声明式映射创建对应的 Python 模型类。请包含必要的导入、Base 类继承、字段定义、关系以及__tablename__。”AI 可能会生成类似下面的代码并且因为 RULES 的约束代码风格会符合你的预期# src/models.py from sqlalchemy import String, Text, Boolean, DateTime, ForeignKey from sqlalchemy.orm import Mapped, mapped_column, relationship from datetime import datetime from .database import Base class User(Base): __tablename__ users id: Mapped[int] mapped_column(primary_keyTrue, indexTrue) username: Mapped[str] mapped_column(String(50), uniqueTrue, indexTrue, nullableFalse) email: Mapped[str] mapped_column(String(255), uniqueTrue, indexTrue, nullableFalse) hashed_password: Mapped[str] mapped_column(String(255), nullableFalse) is_active: Mapped[bool] mapped_column(defaultTrue) created_at: Mapped[datetime] mapped_column(DateTime, defaultdatetime.utcnow) posts: Mapped[list[Post]] relationship(Post, back_populatesauthor) class Post(Base): __tablename__ posts id: Mapped[int] mapped_column(primary_keyTrue, indexTrue) title: Mapped[str] mapped_column(String(200), nullableFalse) slug: Mapped[str] mapped_column(String(200), uniqueTrue, indexTrue, nullableFalse) content: Mapped[str] mapped_column(Text, nullableFalse) summary: Mapped[str] mapped_column(String(500)) status: Mapped[str] mapped_column(String(20), defaultdraft) # draft or published published_at: Mapped[datetime] mapped_column(DateTime, nullableTrue) author_id: Mapped[int] mapped_column(ForeignKey(users.id)) created_at: Mapped[datetime] mapped_column(DateTime, defaultdatetime.utcnow) updated_at: Mapped[datetime] mapped_column(DateTime, defaultdatetime.utcnow, onupdatedatetime.utcnow) author: Mapped[User] relationship(User, back_populatesposts) categories: Mapped[list[Category]] relationship(secondarypost_categories, back_populatesposts)接着生成 API 路由和 Pydantic 模型。继续让 AI 根据 SPEC 中的 API 设计和 BACKEND_RULES 中的 FastAPI 规范创建schemas.py和api/posts.py等文件。AI 会生成结构清晰、带有完整类型提示和依赖注入的路由。3.3 第三步前端界面生成当后端核心 API 就绪后至少有了清晰的接口定义切换到前端部分。在 AI 聊天中将上下文切换为PROJECT_SPEC.md和FRONTEND_RULES.md。给 AI 指令“根据后端设计的 API参考 SPEC遵循 FRONTEND_RULES.md 规范使用 Next.js 14 App Router 和 TypeScript创建博客首页用于展示文章列表。需要包含定义从/api/posts获取数据的 TypeScript 接口类型。创建一个使用 TanStack Query 的useQueryhook 来获取数据的自定义 hook。创建首页页面组件 (app/page.tsx)展示文章标题、摘要、发布日期和分类标签。使用 Tailwind CSS 进行样式化确保响应式设计。”AI 会生成类型安全的接口定义、封装良好的数据获取逻辑以及符合你设计规范的 React 组件。3.4 第四步部署配置生成项目开发接近尾声时引入DEPLOY_RULES.md。指令可以是“请根据 DEPLOY_RULES.md 中的模板为这个 SimpleBlog 项目生成完整的部署配置文件包括后端 (Dockerfile.backend) 和多阶段构建的前端 (Dockerfile.frontend) Dockerfile。整合数据库、后端、前端的docker-compose.yml文件。一个基本的nginx.conf配置将前端应用代理到后端 API。”AI 会输出生产就级的配置文件你只需要微调端口、环境变量名等细节即可。4. 高级技巧与避坑指南经过多个项目的实践我总结出一些让这套工具箱发挥最大效能的技巧以及需要特别注意的“坑”。4.1 如何定制属于你自己的 RULES 文件工具箱自带的 RULES 文件是一个绝佳的起点但真正的威力在于将其“本地化”。不要直接使用而是将其作为模板进行深度定制。从你的现有项目提取规范打开你最近一个写得最满意、结构最清晰的项目。将其中关于目录结构、代码风格、通用工具函数、错误处理方式、日志格式等约定逐条整理并添加到对应的 RULES 文件中。例如如果你习惯用logger.catch装饰器进行自动错误日志记录就把这条写进 BACKEND_RULES。编码你的“血泪教训”把你在过去项目中踩过的坑变成规则。例如“禁止在循环内进行数据库查询应使用selectinload或joinedload策略优化 N1 问题”“所有用户输入在进入数据库前必须使用特定的 XSS 过滤函数处理”。这些经验规则是 AI 无法凭空学会的但通过 RULES 文件你可以让它“继承”你的经验。保持更新技术栈和最佳实践在演进。定期回顾你的 RULES 文件更新过时的库版本推荐如从 Pydantic v1 升级到 v2 的语法或加入新的、被社区验证过的模式。4.2 与不同 AI 助手的协作策略不同的 AI 助手有不同的特性和上下文处理能力需要调整使用策略。Claude Code / Cursor它们对项目级上下文的理解能力强适合将整个 RULES 文件目录作为“项目知识库”加载。你可以直接打开包含所有规则文件的项目然后让 AI 在整个项目上下文中工作。它的优势是能保持长期的、跨文件的上下文记忆生成代码时能自动引用相关规范。GitHub CopilotCopilot 的上下文窗口相对较小且更专注于行内或文件内的补全。对于 Copilot最佳实践是将 RULES 文件中的关键规范提炼成更简短的注释或代码片段放在当前文件的头部。例如在 Python 文件开头加上# rule: Use SQLAlchemy 2.0 style mapped_column.或者在.cursor/rules/目录下放置自定义规则片段如果支持。通用策略对于任何 AI在开始一个复杂任务前先给它“喂”最相关的 1-2 个规则文件。例如在写 API 端点前先提供BACKEND_RULES.md中关于 FastAPI 和 Pydantic 的部分。任务切换时如从后端转到前端明确告知 AI“我们现在要开始写前端组件了请忘记之前的后端规则并遵循以下新的前端规则”然后提供FRONTEND_RULES.md。4.3 常见问题与解决方案实录即使有了完善的工具箱在实际协作中仍会遇到一些典型问题。下面是我遇到过的和解决方案问题现象可能原因排查与解决思路AI 生成的代码不符合我的目录结构RULES 文件中关于项目结构的描述不够具体或 AI 上下文未包含该部分。1. 检查 RULES 文件确保目录结构部分用清晰的树状图或列表描述。2. 在给 AI 的指令中明确指定生成文件的路径如“请在src/api/v1/endpoints/目录下创建posts.py”。3. 先让 AI 生成整个项目的树状图确认无误后再生成具体代码。生成的 API 缺少我想要的特定中间件或依赖RULES 文件可能只定义了基础规范未涵盖所有高级特性。1. 在 PROJECT_SPEC.md 的“技术栈”或“非功能性需求”部分明确列出需要的中间件如“需要添加请求限流中间件和 CORS 配置”。2. 在给 AI 的指令中补充“请确保在所有公共 API 路由上添加 CORS 中间件配置允许的来源为*。”前端组件样式与设计系统不符FRONTEND_RULES.md 中的 Tailwind CSS 或组件规范不够细致。1. 将你的设计系统如主色、圆角、阴影、字体以 Tailwind 配置扩展或 CSS 变量的形式明确写入 RULES 文件。2. 提供几个“样板组件”如 Button、Card的完整代码作为示例让 AI 学习你的样式模式。3. 指令中指定“请使用bg-primary-600作为主按钮颜色使用rounded-lg作为默认圆角。”AI 混淆了不同环境的配置DEPLOY_RULES.md 可能没有清晰区分开发、测试、生产环境。1. 在 RULES 文件中明确定义不同环境的配置模板如docker-compose.override.yml用于开发docker-compose.prod.yml用于生产。2. 指令中明确环境“请生成用于生产环境的 Docker Compose 配置使用.env.production文件。”代码功能正确但性能不佳或存在安全隐患RULES 文件侧重于风格和结构可能缺少性能和安全的硬性规则。1. 在 BACKEND_RULES 中增加“安全与性能”章节列出规则如“所有数据库查询必须使用参数化查询以防止 SQL 注入”、“分页查询必须设置limit上限”。2. 在代码审查阶段针对性地让 AI 检查“请审查刚才生成的user_login函数是否存在密码明文传输或存储的风险请根据安全规则修正。”最重要的心得永远记住AI 是你的“超级实习生”它执行力强但缺乏全局观和深层经验。你是“架构师”和“项目经理”。工具箱SPECRULES是你给这位实习生编写的、极其详尽的工作手册和设计图纸。你的职责是1) 制定清晰、无歧义的图纸填好 SPEC2) 确保手册覆盖所有关键工艺标准完善 RULES3) 在关键节点进行评审和纠偏审查 AI 的输出。这套流程磨合熟练后你将能腾出大量精力专注于真正的业务逻辑和创新设计而将重复性的、模式化的编码工作高效地委托出去。