在被Vibe Coding折磨之后 我才明白在开始之前就得想明白的那些事

在被vibe coding反复鞭尸之后我才明白这个工具很强大但不是万能的在驾驭强大的工具之前你首先得明白你要让这个工具做什么以及怎么做不然就是被牵着鼻子走。Vibe Coding 项目启动模板重要提醒每次开始新项目前务必完整填写此模板未填写禁止启动代码开发避免无效返工。一、项目定位必填明确项目核心价值1.1 项目名称填写规范简洁明了贴合项目功能避免模糊化命名例AI文本润色工具1.2 一句话描述这个项目是___核心功能/产品形态帮助___目标用户群体解决___具体痛点/需求问题。 示例这个项目是一款轻量AI代码注释工具帮助程序员快速生成规范注释解决注释编写繁琐、不统一的问题。1.3 目标用户用户角色___例后端程序员、产品经理、在校学生用户水平___二选一/补充会用 API / 会点界面 / 纯小白用户痛点___精准描述避免笼统例手动编写注释耗时久且注释风格不统一影响代码可读性二、数据流必填清晰梳理数据流转逻辑2.1 输入输入形式□ 文字 □ 语音 □ 文件 □ 按钮点击 □ API 调用可多选输入示例___贴合输入形式例Python代码片段文字、本地txt代码文件文件2.2 输出输出形式□ 文字 □ 文件 □ 数据库 □ 界面展示可多选输出示例___贴合输出形式例带规范注释的Python代码文字、生成的注释文档文件2.3 核心流程必填不超过5步清晰可落地第1步___具体操作 → 结果___明确产出 第2步___具体操作 → 结果___明确产出 第3步___具体操作 → 结果___明确产出 第4步___可选具体操作 → 结果___明确产出 第5步___可选具体操作 → 结果___明确产出2.4 结束标志明确流程终止条件怎么算完成___例输出符合预期格式的结果且无报错成功输出是什么___例带规范注释的代码、无错误提示失败输出是什么___例错误提示文案、空输出、异常日志三、状态机必填梳理系统运行状态及流转3.1 所有状态状态名说明能否直接转到 ENDSTART___例系统初始化等待用户输入□ 能 □ 不能___例处理中___例系统正在处理用户输入数据□ 能 □ 不能___例校验中/异常中___例校验输入合法性/处理过程中出现异常□ 能 □ 不能END结束流程正常终止或异常终止N/A3.2 状态流转图清晰标注正常/异常流转START → ___正常状态1 → ___正常状态2 → ___正常状态3 → END ↓异常触发 [失败] → ERROR异常状态 → END3.3 边界情况规避流转漏洞状态 A 能否转到状态 B□ 能 □ 不能原因___例START状态未接收输入无法直接转到处理中状态四、模块划分必填明确模块职责降低耦合4.1 核心模块必选支撑项目核心功能模块名职责输入输出___例输入处理模块___例接收、校验用户输入格式标准化___例用户输入的原始数据___例标准化后的合法输入数据___例核心业务模块___例执行核心业务逻辑处理标准化输入___例标准化后的输入数据___例处理后的核心结果___例输出模块___例将核心结果格式化输出给用户___例处理后的核心结果___例符合预期格式的最终输出4.2 辅助模块可选提升系统可用性模块名职责能否去掉___例日志模块___例记录系统运行日志、错误日志便于排查问题□ 能 □ 不能不能请说明原因4.3 模块依赖关系明确模块调用顺序___模块1 → ___模块2 → ___模块3 ↓可选依赖 ___模块4五、技术选型必填结合项目需求合理选型5.1 运行时语言□ Python □ Node.js □ Go □ 其他___单选/补充版本___例Python 3.10、Node.js 16.x5.2 LLM如不使用可跳过提供商□ OpenAI □ Anthropic □ 本地 □ 其他___单选/补充模型___例GPT-4o、Claude 3 OpusAPI Key 环境变量___例OPENAI_API_KEY5.3 存储长期存储□ MySQL □ PostgreSQL □ SQLite □ MongoDB □ 不需要单选会话存储□ Redis □ Memory □ 数据库表单选文件存储□ 本地 □ S3 □ HDFS □ 不需要单选5.4 通信同步调用□ REST □ gRPC单选/多选异步通知□ WebSocket □ Server-Sent Events □ Polling单选/多选无则不选六、错误处理必填规避系统异常崩溃6.1 必然失败的场景提前预设处理方案场景处理方式LLM 调用超时___例重试2次仍失败则返回超时提示记录错误日志用户输入非法___例返回明确的非法提示引导用户重新输入不进入核心流程网络断开___例提示网络异常保存当前进度如有等待网络恢复后重试用户中途取消___例终止当前流程清理临时数据返回取消提示6.2 错误级别明确错误处理优先级致命错误___例核心模块崩溃、数据库连接失败 → 停止流程返回错误可忽略错误___例辅助模块日志记录失败 → 记录日志继续执行七、扩展性必填为后续迭代预留空间7.1 以后加新功能改哪几个文件1. ___例core/handler.py 核心处理逻辑文件 2. ___例api/router.py 接口路由文件 3. ___例config/settings.py 配置文件7.2 加新 Agent/模块改哪里1. ___例新增模块目录在core/__init__.py 中注册新模块 2. ___例修改模块依赖关系调整调用逻辑7.3 换 LLM 改哪里1. ___例修改llm/client.py 中LLM调用逻辑、模型配置替换API Key环境变量八、三行核心设计必填浓缩项目核心逻辑我的输入是___精准描述例用户上传的Python代码文件 我的输出是___精准描述例带规范类/方法注释的代码文件 核心流程是___ → ___ → ___提炼3步核心例接收文件 → 解析代码 → 生成注释九、检查清单启动开发前必核开始写代码前确认以下项均已完整回答□ 项目名称□ 一句话价值1.2 一句话描述□ 目标用户1.3 所有子项□ 输入形式2.1□ 输出形式2.2□ 核心流程不超过5步2.3□ 所有状态3.1□ 状态流转3.2□ 核心模块划分4.1□ LLM 配置如使用5.2□ 存储方案5.3□ 错误处理策略6.1、6.2□ 扩展性规划7.1、7.2、7.3□ 三行核心设计8十、每次加新功能前检查迭代必核新增功能___明确新增功能名称/描述□ 这是核心流程还是锦上添花核心流程优先保障□ 需要新增状态吗如需补充到3.1、3.2□ 需要修改哪些现有模块明确模块及修改点□ 会不会让系统变复杂尽量简化避免过度设计□ 能不能先写注释验证逻辑先验证逻辑再写代码温馨提示填完此模板确认检查清单全部勾选后再启动代码开发高效避坑