1. 项目概述为AI开发构建清晰的项目蓝图如果你和我一样已经深度依赖像 Cursor、Claude Code 或 GitHub Copilot 这样的 AI 编程助手那你一定经历过这种挫败感你满怀激情地描述了一个新功能AI 助手也“理解”了并开始生成代码。但几轮对话下来你发现它生成的代码风格和你之前的项目不一致或者它完全误解了某个核心的业务规则又或者它把一个简单的功能拆解得支离破碎导致你不得不花大量时间在聊天窗口里反复解释、纠正和回溯。这感觉就像在指挥一个极其聪明但患有间歇性失忆的队友你不得不一遍又一遍地重复项目的基本规则。问题的根源往往不在于 AI 的能力而在于我们提供给它的“上下文”是零散、模糊且不完整的。我们习惯于直接跳进代码里边写边想但 AI 助手需要的是一个清晰、结构化的项目蓝图才能与我们保持同步。这正是 Framewright 要解决的核心痛点。它不是一个代码生成器而是一个项目框架定义向导。它的目标很简单在你写下第一行代码之前引导你系统地定义好项目的方方面面——从身份、架构到具体的功能和任务并输出一套 AI 友好的结构化文档。当你把这套文档放入项目根目录你的 AI 助手就拥有了一个稳定、可靠的“项目记忆”从而大幅提升协作效率和代码质量。简单来说Framewright 帮你把“在脑子里”和“在聊天记录里”的项目规划沉淀成一份机器AI和人你和未来的协作者都能高效理解的“宪法”。这尤其适合启动新项目、重构旧项目或者当你需要将项目交接给 AI 或他人时确保思路的连贯性。2. 核心设计理念为什么“先文档后代码”在AI时代至关重要在传统的敏捷开发或个人项目中我们可能用一张思维导图、几个用户故事卡片或者干脆就在脑子里过一遍就开始编码了。这种做法在纯人力开发时其问题会被开发者的连续记忆和临场决策所掩盖。但 AI 助手的工作方式截然不同它没有长期记忆在单次会话或有限上下文窗口内它严格依赖于你提供的提示词Prompt的清晰度和完整性。2.1 AI 开发的典型困境与 Framewright 的解法让我们具体看看那些让 AI “翻车”的场景以及 Framewright 如何通过结构化文档来规避困境一上下文断裂与重复解释现象在会话 A 中你定义了用户认证的规则到了会话 B 开发支付功能时AI 已经“忘记”了用户角色和权限体系你需要重新解释一遍。Framewright 解法生成独立的FEATURES/user-authentication.md文件明确定义业务规则如“用户分普通用户和管理员”。当开发支付功能时AI 通过读取该文件能自动关联上下文知道“只有认证用户才能发起支付”以及“管理员可以查看所有交易记录”。困境二架构与风格漂移现象今天让 AI 用 React 函数组件和useState明天它可能给你生成一个类组件你希望 API 响应统一包裹在{ data, code, message }结构里但 AI 有时会返回裸数据。Framewright 解法通过CONVENTIONS.md和ARCHITECTURE.md或PROJECT.md中的架构部分强制约定。CONVENTIONS.md会明确规定“前端使用 React 函数组件与 Hooks”、“所有 API 响应必须遵循{ success: boolean, data: any, message?: string }格式”。AI 在每次生成相关代码时都会参考这份约定确保一致性。困境三任务拆解模糊AI 无从下手现象你给 AI 一个模糊的指令“实现一个博客系统”。这个任务太大AI 要么生成一个过于简化的样板要么陷入混乱因为它不知道从哪里开始以及“完成”的标准是什么。Framewright 解法强制进行“功能 - 任务”的逐级拆解。首先在FEATURES/下创建blog-system.md描述核心能力。然后在TASKS/下创建如task-001-setup-express-server.md、task-002-design-post-schema.md、task-003-create-post-crud-api.md等具体任务文件。每个任务文件都包含清晰的“完成定义”Definition of Done告诉 AI 和开发者做到哪一步才算这个任务真正完成。2.2 结构化文档作为“单一可信源”Framewright 输出的文档集构成了项目的“单一可信源”。它带来的好处是立体的对 AI提供了稳定、全面、可检索的上下文减少了幻觉和错误猜测。对开发者你迫使你在编码前深入思考厘清需求本身就是一个极好的设计过程。它也是你个人或团队的项目笔记和知识库。对协作无论是与未来的你、其他团队成员还是客户沟通这份文档都是一个绝佳的沟通锚点确保所有人对项目的理解在同一频道上。3. 功能深度解析与实战应用指南Framewright 通过一个精心设计的向导流程将项目定义这个宏观任务分解为可操作的步骤。我们来深入看看每个环节该如何有效利用。3.1 向导流程拆解如何回答每一个问题向导的每一步都不是随意设置的它们对应着 AI 理解和构建项目所需的关键信息维度。项目身份与核心栈实战要点这里不仅要填项目名称和描述更要清晰定义技术栈。例如不要只写“前端React”而应该写“前端React 19 TypeScript Vite Tailwind CSS”。对于“主要用户”和“核心价值”尝试用一两句非常具体的话描述这能帮助 AI 理解项目的领域和基调。例如不是“一个任务管理工具”而是“一个为小型远程团队设计的、强调极简主义和键盘快捷操作的任务管理工具”。架构设计实战要点这里适合用分层图或列表来描述。例如对于一个全栈应用你可以定义表示层 (UI)React 组件通过 TanStack Query 获取数据。API 层Express.js RESTful API负责业务逻辑和路由。数据访问层Prisma ORM连接 PostgreSQL 数据库。基础设施层Docker 容器化部署在 VPS 上。注意事项即使你的项目很简单也建议至少区分“前端”和“后端”或“客户端”与“服务端”。这能帮助 AI 在生成代码时清晰地知道当前文件所属的层次和职责。约定与样式指南CONVENTIONS.md 是重中之重这是保证代码一致性的“法律文件”。你需要明确命名规范变量用camelCase组件用PascalCase常量用UPPER_SNAKE_CASE。文件结构/src/components/ui/存放通用UI组件/src/hooks/存放自定义 Hooks。API 设计路径前缀/api/v1/使用 JSON Web Tokens (JWT) 进行认证。状态管理全局状态使用 Zustand服务端状态使用 TanStack Query。错误处理所有异步操作必须使用try-catch并向上抛出统一格式的错误对象。STYLING.md 对于前端项目至关重要定义你的设计系统。包括主色、辅助色、成功/警告/错误色值Hex 或 RGB字体族如font-sans: Inter, system-ui, sans-serif以及间距、圆角等基础 Token。如果你使用像 shadcn/ui 这样的组件库在这里注明AI 就会倾向于使用其中定义好的组件。功能与任务分解这是将想法落地的核心环节。一个功能Feature代表一个对用户有价值的、相对完整的能力模块比如“用户认证”、“文章发布与管理”、“支付订阅”。创建功能文件在FEATURES/下为每个核心功能创建一个.md文件。内容应包括功能描述用一两句话说明这是什么。用户故事以“作为 [角色]我希望 [做什么]以便于 [达到什么目的]”的格式描述。业务规则与验收条件这是最关键的。用列表形式清晰罗列所有规则。例如对于“用户注册”功能用户需提供邮箱、用户名和密码。密码长度至少8位需包含字母和数字。邮箱必须唯一注册前需校验是否已被占用。注册成功后系统应发送一封验证邮件。用户邮箱验证前处于“未激活”状态仅能访问公开页面。将功能拆解为任务在TASKS/下为每个功能分解出具体的、可执行的任务。任务应该足够小 ideally 能在一次 AI 会话中完成。Framewright 会自动为任务编号如task-001并关联到所属功能。任务文件的核心每个任务文件都包含一个“Definition of Done”部分。这是给 AI 的明确完工清单。例如对于任务“创建用户注册 API 端点”DoD 可能是在/src/api/auth/下创建register.ts文件。实现 POST/api/v1/auth/register端点。请求体验证邮箱格式、唯一性、用户名、密码强度。密码使用 bcrypt 加密后存入数据库users表。生成 JWT Token 并返回给客户端。调用邮件服务发送验证链接可先模拟日志输出。编写对应的单元测试覆盖成功和失败场景。3.2 输出文件体系你的项目“宪法”目录Framewright 最终生成的是一个可直接放入项目根目录的文档框架。理解每个文件的作用能让你更好地使用它们。文件/目录核心内容与使用场景PROJECT.md项目总纲。包含项目愿景、技术栈、架构图、运行指南。适合新成员快速了解项目全貌。AI 在开始任何新任务前都应先浏览此文件以建立整体认知。CONVENTIONS.md编码宪法。所有代码层面的约定。AI 在生成任何代码文件时都应持续参考此文件确保风格一致。STYLING.md设计圣经前端项目。定义视觉设计规范。AI 在编写 JSX/HTML 和 CSS 时应据此选择颜色、字体和间距类。SCHEMA.md数据蓝图。数据库表结构、关系、索引定义。AI 在生成数据模型、API 或查询语句时以此为准。FEATURES/需求仓库。每个文件是一个独立的业务功能规格说明书。当 AI 开发某个具体功能时深入阅读对应的文件。TASKS/工作包清单。每个文件是一个具体、可执行的工作项关联到特定功能并包含明确的完成定义。开发者或 AI 可逐个完成。CONTEXT-WINDOW-STARTERS.md提示词弹药库。这是 Framewright 的精华产出之一。它为每个任务生成了一个优化过的、开箱即用的提示词Prompt。你可以直接复制粘贴到 Cursor、Claude 等工具的聊天框它已经包含了指向相关PROJECT.md、CONVENTIONS.md和对应FEATURE.md的引用指令让 AI 瞬间获得精准上下文。3.3 从文档到代码实战工作流假设我们已经用 Framewright 为“个人博客系统”生成了全套文档。现在我们如何与 AI 协作开始真正的编码初始化项目在本地创建项目文件夹将 Framewright 生成的PROJECT.md、CONVENTIONS.md、FEATURES/、TASKS/等全部复制到根目录。打开TASKS/目录你会发现第一个任务通常是task-000-skeleton-deployment.md。这是 Framewright 贴心地为你生成的“项目骨架部署”任务旨在搭建最基础的环境如初始化 Git安装依赖创建基础目录结构。启动 AI 助手打开你的 Cursor 或 Claude Code将整个项目文件夹作为上下文或上传相关文档。复制提示词打开CONTEXT-WINDOW-STARTERS.md找到对应task-000的提示词块。它可能长这样## Starter for task-000-skeleton-deployment.md Please refer to the project documentation in the current context, especially PROJECT.md and CONVENTIONS.md. Now, help me complete the following task: **Task ID:** task-000 **Title:** Skeleton Deployment Project Setup **Linked Feature:** Project Foundation **Definition of Done:** - Initialize a new Node.js project with npm init -y and create a package.json. - Install core dependencies as per PROJECT.md: express, react, etc. - Set up basic project structure: /src for source code, /public for static assets. - Create a .gitignore file for Node.js projects. - Create a minimal README.md with project name and setup instructions. - Verify the setup by running a simple “Hello World” server (if backend) or app (if frontend). Lets start by initializing the project.粘贴并执行将这个提示词粘贴到 AI 聊天框并发送。由于提示词已经包含了精确的任务描述和完成标准并指引 AI 去参考PROJECT.md了解技术栈和CONVENTIONS.md了解代码规范AI 会给出非常精准、符合项目约定的操作建议或直接生成代码。迭代推进完成task-000后按照编号顺序或优先级继续用同样的方法处理task-001、task-002。每个任务都因其清晰的边界和上下文变得像组装乐高积木一样可控。4. 高级技巧与避坑指南经过多个项目的实践我总结出一些能让 Framewright 发挥最大效能的技巧以及一些需要避免的常见陷阱。4.1 让文档保持活力的技巧技巧一将文档集成到开发流程中不要让它变成“写完就忘”的摆设。在团队中可以将FEATURES/下的文件作为需求评审的输入将TASKS/作为 Sprint 待办事项的来源。在个人项目中每完成一个任务就去对应的任务文件里打勾或做记录。技巧二善用“导入现有项目”功能如果你是在为一个已有项目添加 Framewright 文档不要从零开始。使用向导中的“导入”功能可以粘贴你的项目文件树或现有数据库 SchemaFramewright 会以此为基础帮你快速生成架构和约定的初稿你只需在此基础上补充和细化。技巧三CONTEXT-WINDOW-STARTERS.md是可定制的Framewright 生成的初始提示词模板很好但你可以根据你常用的 AI 助手Cursor, Claude, ChatGPT的“性格”进行微调。例如如果你发现 Claude 对文件路径的引用方式有偏好你可以统一修改这个文件中的提示词格式使其更有效。技巧四为复杂业务规则创建术语表如果项目涉及复杂的领域逻辑可以在PROJECT.md或单独创建一个GLOSSARY.md文件定义关键术语。例如在电商项目中明确定义“SKU”、“SPU”、“订单状态流转”等能极大减少 AI 的误解。4.2 常见问题与排查问题一AI 似乎还是忽略了文档里的某个约定。排查首先检查你的CONVENTIONS.md是否写得足够具体、无歧义。例如“使用 async/await”不如“避免使用.then().catch()统一使用try-catch包装异步操作”来得明确。其次在给 AI 的提示词中可以更强势地引用约定文件例如“请严格遵守CONVENTIONS.md中第 3 条关于 API 响应格式的约定。”解决强化提示词指令并在 AI 生成代码后进行快速的代码风格检查可以使用 ESLint 等工具其规则也应与CONVENTIONS.md对齐。问题二任务拆得太细或太粗。排查任务拆解是一门艺术。太细如“创建一个 React 函数组件文件”会导致任务爆炸管理 overhead 很高太粗如“实现用户管理系统”又会让 AI 不知所措。解决一个好的任务是一个能产生明确、可验证输出的小单元例如“创建用户注册 API 端点及输入验证”、“实现博客文章列表页的 React 组件与数据获取”。如果发现一个任务需要 AI 进行多轮复杂对话才能完成就应该考虑将其拆分。Framewright 允许你随时回去调整任务分解。问题三文档和实际代码逐渐脱节。排查这是动态文档系统的通病。当你因为实现困难而临时修改了某个业务规则或者优化了某个 API 设计但忘了更新对应的FEATURE.md或SCHEMA.md。解决建立轻量级的同步习惯。在提交代码Commit前花一分钟检查相关功能或任务文档是否需要更新。可以将更新文档作为每个任务“Definition of Done”的最后一项。此外Framewright 的“验证警告”功能如提示有功能缺少关联任务也能在导出时帮你发现一些明显的脱节。问题四在非常小或实验性的项目中使用 Framewright 感觉“杀鸡用牛刀”。观点对于真正的“一次性”脚本或原型确实可能不需要。但对于任何你预计会存活超过一天、或者未来可能扩展的项目即使它现在很小花 15-20 分钟用 Framewright 走一遍流程也是值得的。这不仅能帮 AI更能帮你自己理清思路。你可以只填写最核心的部分项目身份、主要技术栈、一两个关键约定略过细节快速生成一个简化版的框架。我个人最深的一个体会是Framewright 最大的价值与其说是“规范 AI”不如说是“规范思考”。它强迫我在兴奋地敲代码之前先停下来把那些模糊的想法变成清晰的文字。这个过程本身就能消灭掉一大半潜在的设计缺陷和逻辑矛盾。当我和 AI 都基于同一份清晰的蓝图工作时那种顺畅的协作感会让你觉得之前所有因上下文丢失而浪费的时间都得到了加倍的补偿。它不是一个增加负担的工具而是一个通过前期的小投入换取整个开发周期大幅效率提升的杠杆。