← 返回技巧手册使用说明 / UPDATED 2026.08

项目开发提示词实战手册

开篇速查：推荐模型与工具

模型建议核对日期：2026-08-04。模型版本会快速变化；生产接入前应再查官方模型列表，并用自己的样本比较质量、延迟和成本。会议中的 Cursor、Claude Code、Copilot、Hermes、OpenClaw 属于工具或 Agent 框架，不是基础模型。

推荐产品：Codex、Claude Code、Cursor（涉及仓库、终端、测试和跨文件修改时）。 常用工具：Codex / Claude Code、GitHub、Figma、浏览器自动化、Playwright、CI/CD、Docker 与可观测性工具。

  • 需求到上线自动流水线：需求 Agent 生成用户故事和验收，架构 Agent 冻结契约，各岗位并行实现，QA/安全独立验收，发布 Agent 按门禁上线。
    • 模型对比：首选 GPT-5.6 Sol 做复杂跨阶段开发；超长资料和多模态仓库可试 Kimi K3；常规子任务用 GPT-5.6 Terra 降低成本。
  • 失败自动变资产：每次返工、报错和人工纠正自动进入失败案例库，转成测试、监控或提示词评测，避免同类问题重复发生。
    • 模型对比：批量优先 DeepSeek V4 Flash；OpenAI 链路用 GPT-5.6 Luna；Claude 链路用 Claude Haiku 4.5。三者都适合高频分类和提取，难例再升级质量档。
  • 一份业务Schema驱动多端：从 OpenAPI/事件 Schema 自动生成后端类型、前端SDK、移动端模型、Mock和契约测试。
    • 模型对比：OpenAI 链路选 GPT-5.6 Terra；Claude 链路选 Claude Sonnet 5；复杂跨文件一致性可试 DeepSeek V4 Pro。产物仍须由代码生成器、类型检查和契约测试验证。
  • Agent负责判断，脚本负责强制：让Agent做分析、拆分和审查；格式化、测试、扫描、构建和部署门禁交给确定性脚本与CI。
    • 模型对比：复杂判断用 GPT-5.6 Sol 或 Claude Opus 5；高频日常审查用 Kimi K2.7 Code。模型不代替格式化器、测试器、扫描器和部署门禁。

基于本机 Codex 历史中 8,276 条用户消息整理。项目开发类命中 2,556 条，精确去重后 958 条；前端与页面样式类命中 1,710 条，去重后 591 条。

本手册适合设计整体任务；需要按岗位直接调用时，配合《项目开发岗位细分提示词手册》。后者已经拆分产品/需求、架构、前端、后端、数据库、DevOps/服务器、SRE、QA、安全、移动端、AI/数据、性能和发布审查岗位。

0. GitHub 项目中的三层提示词结构

参考 GitHub Copilot 的定制方式，项目规则不应全部复制进每次聊天：

  1. 长期规则：技术栈、目录约定、命令、不变量和验收，放在 AGENTS.md 或仓库级指令中。
  2. 岗位规则：前端、后端、数据库和服务器等专业职责，做成专项代理或路径级规则，并只开放必要工具。
  3. 任务提示词：某个功能、故障或发布的具体目标，使用本手册中的模板，完成后即可结束。

格式化、扫描、测试和部署门禁等确定性动作，应放进 CI 或 Hook；提示词负责判断和协作，自动化负责强制执行。

快速选岗：

你要做的事主岗位必须提供
页面、组件、响应式前端工程师设计输入、接口、设备、截图验收
API、权限、业务规则后端工程师业务规则、契约、数据、错误语义
表结构、SQL、迁移数据库工程师读写模式、规模、停机和回滚要求
Linux、云、部署、CI/CDDevOps/服务器工程师拓扑、环境、权限、RTO/RPO
告警、稳定性、容量SRE关键旅程、SLI/SLO、故障历史
测试与发布判断QA/发布经理验收、风险、环境和构建
漏洞与权限风险安全工程师资产、数据、信任边界、授权范围

1. 历史提示词给出的核心结论

历史中的开发提示词通常擅长描述“要做什么”，但较少明确“怎样算做完”：去重后的项目开发提示词中，35% 明确了交付物，只有 6% 写出验收标准、22% 要求验证；前端提示词中只有 4% 写出验收标准、23% 要求验证、15% 提供参考物。

这正是返工的主要来源。历史中出现了 150 条视觉不满意表达、131 条功能不可用表达、103 条要求重新检查的提示，以及 316 条“继续、不要停、直到完成”类追促。更省事的写法，是把后续追问提前放进首轮提示词。

高质量开发提示词应同时回答六件事：

  1. 为什么做：业务背景、用户和问题。
  2. 做到哪里：范围、优先级和明确不做的内容。
  3. 在什么基础上做：仓库现状、技术栈、已有组件和约束。
  4. 交付什么：代码、页面、接口、迁移、测试、文档。
  5. 怎样证明完成：可观察、可执行的验收标准。
  6. 如何收尾：运行、测试、截图、复查和未解决问题说明。

可以记成：目标 → 现状 → 边界 → 交付 → 验收 → 证据。

2. 通用项目开发母模板

PROMPT
请在【仓库/项目】中完成【目标】。

一、业务背景
- 使用者：【目标用户】
- 当前问题：【具体问题及影响】
- 本次优先目标：【最重要结果】

二、开始前检查
- 阅读项目结构、README、AGENTS.md、相关配置和现有实现。
- 找到可复用组件、接口、数据模型和测试方式。
- 不确定的地方先通过代码和运行结果确认；只有会改变业务方向的选择才需要询问我。

三、范围
必须完成：
1. 【功能一】
2. 【功能二】
3. 【功能三】

本次不做：
- 【明确排除项】

四、技术与业务约束
- 技术栈：【框架/语言/版本】
- 保持兼容：【现有接口、数据、浏览器或设备】
- 不得：【破坏性行为、假数据冒充真实结果、泄露密钥等】
- 优先复用现有代码；新增抽象必须有实际复用价值。

五、交付物
- 可运行的实现代码。
- 必要的数据库迁移、配置和示例数据。
- 自动化测试或可复现的验证脚本。
- 变更说明和仍存在的风险。

六、验收标准
1. 【用户从哪里进入，执行什么操作，看见什么结果】。
2. 【错误、空数据、加载和权限状态】可正确处理。
3. 【构建、类型检查、测试命令】全部通过。
4. 不破坏【既有关键流程】。

七、执行方式
- 自主完成检查、实现、运行、修复和复测。
- 不要只报告代码已修改；必须给出测试或运行证据。
- 如果遇到无法解决的外部阻塞，说明已尝试内容、证据和最小阻塞点。

最后汇报：完成内容、修改文件、验证结果、已知限制。

3. 前端页面怎样更容易“样式做好”

3.1 不要只说“高级、现代、好看”

这些词没有可复核含义。应把审美要求拆成：

  • 信息层级：用户第一眼、第二眼、第三眼分别看什么。
  • 布局：页面容器宽度、网格、区域关系和密度。
  • 设计令牌：颜色、字体、字号、行高、间距、圆角、阴影、边框。
  • 组件语言：按钮、卡片、表格、表单、导航是否属于同一体系。
  • 内容和素材：真实文案、图片主体、图标来源和空态内容。
  • 动效：反馈性动效与装饰性动效的边界。
  • 响应式：在哪些断点发生怎样的结构变化。
  • 视觉验收：用浏览器截图而非“代码看起来没问题”判断。

3.2 前端视觉完整模板

PROMPT
请实现/重构【页面名称】，使用项目现有【技术栈】。

开始前：
1. 检查现有全局样式、设计令牌、布局组件和可复用业务组件。
2. 打开现有页面，确认实际效果，不要仅阅读代码。
3. 如有参考图，先拆解其布局、层级、色彩、字体、间距和素材关系。

页面目标：
- 用户：【用户类型】
- 核心任务：【用户在页面上必须完成的动作】
- 第一视觉焦点：【内容】
- 次级信息：【内容】

视觉方向：
- 气质：【例如克制、可信、专业、温暖】
- 参考：【截图/网站/既有品牌系统】
- 采用：【明暗模式、主辅色、字体、圆角、间距密度】
- 避免：【过度渐变、无意义玻璃拟态、大面积发光、过多卡片、emoji充当图标、低对比文字】

结构：
1. 【顶部/首屏】
2. 【核心工作区】
3. 【辅助信息区】
4. 【关键操作区】

组件与状态：
- 复用已有 Button、Input、Card、Table、Dialog 等组件。
- 补齐 hover、focus、active、disabled、loading、empty、error、success 状态。
- 所有按钮和导航必须产生真实、可见的结果，不能只是静态装饰。

响应式：
- 桌面端：【布局规则】
- 平板：【布局变化】
- 手机：【堆叠顺序、导航形式、触控尺寸】
- 不允许横向溢出、文字遮挡、关键操作离屏。

内容与素材：
- 使用符合业务的真实示例内容，不使用 lorem ipsum。
- 优先使用项目已有图片和图标库；缺失素材时明确生成或替代策略。
- 图片必须规定比例、裁切、主体位置和背景关系。

视觉验收：
1. 启动项目并在浏览器中打开页面。
2. 分别以【桌面尺寸】和【手机尺寸】截图。
3. 检查对齐、间距、字号、对比度、折行、溢出、状态和交互。
4. 与参考图对比并直接迭代，直到以下标准全部满足：【标准列表】。
5. 最后运行构建、类型检查和相关测试。

交付时提供：页面截图、验证命令结果、修改文件和仍存在的差异。

3.3 按截图还原页面

PROMPT
请根据附件截图还原【页面】。参考图是视觉事实来源，但实现必须适配当前项目。

先分析并列出：
- 页面网格、容器宽度和主要区域尺寸；
- 字体层级、颜色、间距、圆角、边框和阴影；
- 图片比例、裁切方式和主体位置；
- 可交互控件及其状态；
- 截图中不明确、需要合理推断的部分。

实现要求：
- 优先复用现有组件和设计令牌。
- 不要把整个页面做成一张图片。
- 不要为了贴图而使用大量不可维护的绝对定位。
- 在目标分辨率下做截图对比，同时确保其他断点可用。
- 至少完成两轮：首次实现 → 截图对比 → 修正明显差异。

验收：主要结构、视觉层级、间距、文字折行、素材比例和颜色关系与参考一致；交互和响应式可正常使用。

3.4 “不好看”时的有效修正模板

不要只发“还是不好看”。指出差距所在的层级：

PROMPT
当前页面功能可用，但视觉未达到目标。请保留业务逻辑，集中修正以下问题：

1. 信息层级：【例如所有卡片权重相同，核心指标不突出】
2. 布局：【例如内容过满，主区域与侧栏比例失衡】
3. 设计系统：【字号/颜色/圆角/间距不统一】
4. 素材：【图片风格不一致或主体被裁切】
5. 交互状态：【按钮、表单、加载与空态缺失】

目标参考：【参考】。
禁止通过增加渐变、阴影、发光和更多卡片掩盖层级问题。
修改后用相同尺寸重新截图，并逐项说明五类问题是否解决。

4. 分阶段开发比“一口气做完”更稳

大型项目建议使用五个门：

  1. 理解门：输出项目现状、依赖、风险和实施顺序。
  2. 骨架门：让项目能启动，路由、数据模型和接口契约成立。
  3. 纵切门：先完成一条端到端真实业务链路。
  4. 覆盖门：补齐其他功能、边界状态、权限和迁移。
  5. 验收门：自动化测试、浏览器实测、截图、性能与安全检查。

阶段提示词：

PROMPT
继续完成第【N】阶段。开始前读取上一阶段交付和当前工作树，不重复已完成内容。

本阶段目标：【一个可验证结果】
允许修改：【范围】
禁止修改：【范围】
必须验证：【命令/用户流程】
退出条件：【所有验收项满足；否则继续修复】

完成后仅汇报：实际完成、验证证据、遗留问题、下一阶段入口。

5. 调试提示词

5.1 根因诊断

PROMPT
请诊断【错误现象】，先确定根因，不要直接大范围改代码。

环境：【系统、版本、启动方式】
复现步骤：
1. 【步骤】
2. 【步骤】

预期：【结果】
实际：【结果】
错误日志：【日志】
最近变更：【变更】

请依次：复现 → 收集证据 → 缩小范围 → 说明根因 → 给出最小修复建议。
本轮只诊断，不实施修复。

5.2 实施修复

PROMPT
根据已确认根因实施最小修复。

要求：
- 不用吞掉异常、关闭校验或硬编码结果来掩盖问题。
- 增加能防止该问题复发的测试。
- 运行原复现步骤及相关回归测试。
- 若修复改变接口或数据行为，更新相应文档。

交付：根因、修改点、测试证据、影响范围。

6. 代码审查与验收模板

PROMPT
请审查当前变更，重点寻找会造成错误、数据损坏、安全问题、兼容性回退或验收失败的具体问题。

范围：【提交/分支/文件】
业务目标：【目标】
必须保持：【不变量】
验证命令：【命令】

输出规则：
- 按严重程度排序；每项指出文件、位置、触发条件和影响。
- 只报告可操作的问题，不把个人风格偏好当成缺陷。
- 如果没有发现问题，明确说明仍未覆盖的测试风险。

7. 常见失败写法与替换

失败写法问题替换方法
“做得高级一点”无法验证给参考、视觉令牌、禁用项和截图验收
“把整个项目做完”范围失控分阶段，每阶段一个可运行结果
“继续，不要停”没有退出条件写明本阶段验收项与阻塞报告格式
“修复所有问题”不知道问题集合指定复现、日志、范围和回归要求
“照着截图做”可能只追求静态贴图加响应式、交互、组件复用和对比流程
“测试一下”测试口径不清写出命令、用户路径、设备和预期结果
“不要改其他东西”可能阻止必要修复指定允许范围和必须保持的不变量

8. 最省返工的发送顺序

  1. 首轮发送业务目标、范围、约束和验收，不急着写所有实现细节。
  2. 让代理先检查仓库，用事实补足“现状”。
  3. 对重要架构先确认方案；普通实现细节允许代理自主决定。
  4. 每一阶段要求真实运行或截图，不接受只看代码的完成声明。
  5. 用“差距清单”修改，不用模糊情绪词反复重做。
  6. 最后单独进行一次验收或代码审查，避免实现者的完成偏差。

一条好提示词不是最长，而是能让执行者知道：做什么、不要做什么、做到什么程度、拿什么证明。