AI Coding 任务 Prompt

AI Coding 提示词怎么写，取决于这次任务有哪些信息尚未由项目配置提供。项目规则已经保存仓库结构、项目命令和长期边界，Skill 已经保存重复流程，Hook 和 CI 执行确定性动作，权限策略限制工具能力；当前 Prompt 只需说明要改变的状态、已有证据、影响范围、授权边界和完成后必须出现的结果。

Prompt 不需要写成 YAML、XML 或固定表单。局部缺陷可以很短；状态跨过多个责任模块时，才补充相应上下文。判断标准不是字数或字段数量，而是 Agent 能否从当前项目开始调查，在授权范围内完成改变，并确认软件达到目标状态。

AI Coding 提示词只写当前任务

任务 Prompt 只在当前任务中生效。它可以引用已经按目录生效的 AGENTS.md、CLAUDE.md 项目规则、需求说明、错误日志或某个 Skill，但不应该复制这些内容。复制会产生第二份事实源：项目命令变化后，旧 Prompt 仍会要求 Agent 运行已不存在的入口；流程升级后，保存过的模板仍会执行旧步骤。

OpenAI 的提示方式官方文档（在新标签页打开）明确说明，Prompt 不需要技术语法或僵硬公式，较大任务只加入会影响结果的目标、上下文、输出和边界。Anthropic 的 Claude Code Prompt Library（在新标签页打开） 也建议描述结果，让 Claude 自己寻找文件，并在同一请求里提供检查工作的方法。用户负责提供不能从仓库推导的任务事实，Agent 负责调查实现路径。

“你是一名资深全栈工程师”“请深入思考”“保证代码高质量”不能替代任何任务事实。它们没有说明哪个状态错误、什么必须保持不变，也没有提供可验证结果。若项目确实需要固定语言、架构原则或代码标准，应把它们放在长期规则中；若只想改变交付说明的受众或格式，可以在当前 Prompt 里直接写受众和用途。

Prompt 会改变 Agent 的哪些决定

能够读取、修改并运行命令的 Coding Agent 会根据工具返回的结果继续行动，不是只生成一次代码。Claude Code 的工作原理文档（在新标签页打开）把执行过程概括为收集上下文、采取行动、验证结果，三者会随新观察反复交替。Prompt 的每项有效信息都应改变这个循环中的一个决定。

目标状态决定 Agent 何时可以停止。当前现象和复现条件决定它先运行什么、读取什么。权威材料决定需求、代码与运行状态冲突时相信哪一层。范围说明决定它追踪到哪些生产者和直接消费者。授权边界决定哪些本地动作可以直接执行、哪些外部副作用必须停下确认。可观察结果要求它不能用“代码已经写完”代替软件状态。

OpenAI 的 Codex 最佳实践（在新标签页打开）把目标、上下文、约束和完成条件作为较大任务的实用默认项，而不是每次都要填满的表格。单处文案修改不需要列出数据库、Worker 和部署；只有它们确实参与状态变化时，才进入 Prompt。

AI 编程需求怎么描述：先写软件状态变化

“完成账户状态展示”只有功能名称，没有起点和终点。Agent 不知道页面当前缺什么、状态由谁产生、哪些用户能看到，也无法判断一段新代码是否完成需求。

先把任务改成可观察的前后变化。假设产品已经确认三种用户可见状态，而代码路径仍需由 Agent 调查：

当前服务保存账户状态，管理端显示原始值，用户详情页把所有非正常状态显示成同一句提示。目标是让两个界面显示产品说明中的“正常、待审核、受限”三种状态；没有查看权限的用户仍看不到该字段，现有正常账户的操作保持不变。

数据库字段和组件名称仍由当前代码决定。已经确认的现状是状态存在、两个消费者显示不一致；已批准需求决定目标枚举，权限拒绝与正常路径构成对照结果。Agent 可以据此寻找状态的生产者、公共契约和两个界面，而不是在看到第一个文案后直接修改。

结果要写成软件状态，不写成工作动作。“补测试并构建通过”描述的是验证手段；“有权限的管理端与用户详情页显示相同的账户状态，无权限请求仍被拒绝”才是结果。测试、构建和浏览器检查随后用来证明这个结果。

性能、容量或覆盖率目标也需要明确测量条件。只写“加载更快”无法复验；若已批准目标是“在相同数据和设备条件下，目标页面的某项已定义指标低于阈值”，Prompt 应给出指标、阈值、基线来源和测量环境。没有获批阈值时，要求 Agent 自行挑一个数字会把业务选择伪装成技术事实。

用责任和工程链路定义范围

范围不等于预先猜一组文件名。用户通常知道要改变哪个软件行为，却不一定知道它由 API、缓存、前端适配器还是组件拥有。把猜测写成“只能修改这个组件”，可能迫使 Agent 在错误层补兼容；把范围写成“你看着办”，又会允许任务蔓延到无关重构。

Prompt 应说明责任边界和需要保持的相邻行为：先找产生错误状态的责任模块，只修改根因边界与完成任务所需的直接消费者；不要调整无关路由、视觉系统或部署配置。路径已经由错误堆栈、注册关系或需求文档确认时，可以直接引用；路径未知时，让 Agent 从项目规则、入口和调用链查找。

全栈任务也不需要机械列出后端、数据库、管理端、用户端、Worker 和部署六层。先沿状态实际流动的方向选择工程链路：

需求中的业务状态
  → 产生或保存该状态的责任模块
  → 对外契约或事件
  → 直接消费该状态的应用
  → 用户、API、数据或进程结果

如果调查证明数据库结构和公共契约没有变化，它们就不应因“完整”而进入改动。反过来，只要账户状态的含义通过公共契约传递，Prompt 中的“验证直接消费者”就不能被缩减成服务端单元测试。范围由已证明的影响边界扩大，不由模板字段扩大。

非目标只写容易被误改且会产生实际成本的相邻责任。例如“保持现有正常账户操作不变”比“不要修改任何其他代码”更有用：前者提供对照结果，后者可能与修复直接消费者的必要改动冲突。

把事实来源和未知项分开

需求、源码、日志和运行页面回答的问题不同。把它们统称为“上下文”，Agent 可能用旧截图覆盖当前代码，也可能用现有实现反驳已经批准的新需求。

Prompt 可以直接声明来源边界：需求说明决定目标状态；当前代码决定文件位置与实现责任；提供的截图只证明某个视口出现了症状；运行环境是否对应当前源码需要重新确认。来源边界让 Agent 区分已经批准的目标、当前实现和单次运行现象，避免把不同强度的证据合并成一个结论；源码位置仍由 Agent 在仓库中调查。

已知事实只写能够复核的内容，例如错误原文、出现条件、批准文案和必须保持的行为。推测放进待验证假设：“可能与客户端缓存有关，请先复现并沿请求链确认，不要按这个猜测直接修改。”文件、命令和模块关系能够从仓库读取时，不必让用户替 Agent 抄一遍。

需要用户决定的未知项应在修改前写清楚。两种互斥业务规则、不可逆数据迁移、供应商选择和面向外部用户的承诺不能由 Agent 从代码推导。实现路径、测试入口和错误所属模块通常可以通过读取与无副作用命令确认，不应因为一句“不确定就问”而全部退回给用户。

权限边界写成动作

“注意安全”没有告诉 Agent 哪个动作越界。权限边界应对应会发生的外部副作用。例如，实现任务可以允许读取与修改当前工作区、启动本地服务和运行无破坏性检查，同时把生产写入、外部消息、数据删除、付款、部署、提交或推送留给另行授权。任务不涉及某类动作时，不必逐一列出所有危险命令。

任务动词本身也限定授权。“解释这段代码”与“看看为什么失败”通常止于只读结论；“定位根因”不自动包含修改；“修复并验证”允许在目标工作区改代码，却不自动包含提交、推送或部署。把不同终点混成“处理一下”，Agent 只能猜用户要报告、改动还是发布。

“看看这个页面为什么没变”若只要求诊断，Prompt 应以根因、证据和未确认边界结束；不能因为 Agent 找到一处可能的代码差异，就顺便改文件。“修复页面并在本地验证”才把本地写入纳入任务，远端动作仍需要单独出现。

Prompt 里的授权不能扩大客户端实际权限。Claude Code 的权限机制（在新标签页打开）与 Codex 的沙箱和审批策略（在新标签页打开）仍会限制工具能力；文字只能说明用户意图。一个命令被 Prompt 允许、却被权限策略拒绝时，Agent 应报告受阻，不应尝试绕过策略。

停止条件同样写成无法通过安全调查解决的边界：缺少业务决定、必须访问但不可用的目标运行环境、需要未授权外部写入，或发现根因必须改变原先排除的公共契约。缺少一个源码路径不是停止条件，搜索仓库就是下一步；目标测试失败也不是停止条件，失败输出是下一轮调查证据。

“遇到任何不确定先问我”会把普通工程判断都变成中断。“只有产品要求有两种合理解释、继续需要扩大授权，或必须改变明确排除的范围时再停下”能让 Agent 自主调查，同时把业务与授权决定留给用户。

局部缺陷只需要短 Prompt

局部任务的 Prompt 应与影响范围相称。假设一个项目只出现可复现的移动端界面问题，而框架和源文件位置尚未确认：

在 390px 宽度下，账户页的详情按钮文字会越出按钮；桌面布局正常。请先读取当前目录适用的项目规则，复现问题并找到拥有这段布局的源文件。修复移动端溢出，保持桌面尺寸、按钮文案和点击行为不变，只修改根因及必要的直接测试。允许在当前工作区修改并运行本地检查，不要提交或推送。完成后在 390px 和桌面视口各验证一次，说明实际改动、命令结果和没有验证的外部边界。

“把字号改小”或“编辑某个 CSS 文件”都没有进入 Prompt，因为两者属于尚未调查的实现方案。复现条件、桌面对照、授权边界和两个视口的结果已经足够约束这项局部任务。Agent 首轮应读取规则、复现页面或运行相关测试并定位源文件，而不是先创建一套全局响应式抽象。

如果用户已经确认目标组件，可以把路径或截图附上；如果仓库规定必须调用 UI 验证 Skill，只需写“按项目已有 UI 验证流程检查两个视口”，不必把 Skill 的全部步骤粘进 Prompt。任务越局部，越要删除不会改变行动的格式要求和角色口号。

跨层功能怎样写完整 Prompt

跨层任务需要更多信息，不是因为必须填满模板，而是状态会经过多个责任模块。账户状态同时经过服务端、管理端和用户详情页时，一段自然语言 Prompt 可以写成：

请把账户状态从“服务端已有状态、管理端显示原始值、用户详情页统一显示不可用”，改成两个界面都显示已批准需求中的“正常、待审核、受限”三种状态。没有查看权限的用户仍不能取得该字段，正常账户的现有操作保持不变。

目标行为以随任务提供的需求说明为准；当前源码、schema、生成配置和注册关系决定实际负责模块与文件位置。截图只证明当前界面的显示差异，不代表根因。先读取仓库根规则和涉及目录的最近规则，再沿状态生产者、公共契约和两个直接消费者确认最小完整范围，不要按这段描述虚构路径或字段。

允许在当前工作区读取、修改、更新项目要求同步的生成文件、运行已有检查并启动本地预览。不要改无关页面、权限模型或部署配置；不要访问生产数据、提交或推送。如果三种状态的含义仍有互斥解释、需要不可逆迁移，或根因要求改变上述非目标，请说明具体冲突并停止在写入之前。

完成时，先运行仓库已有检查，再分别从状态的直接消费者观察当前结果。交付需要说明状态从什么变成什么、实际修改了哪些责任模块、运行了哪些命令、管理端与用户端分别观察到什么，以及哪些外部环境没有验证。

状态没有经过 API、schema 或某个页面时，那一层就不进入改动。Agent 要先证明状态实际经过哪里，再把修改和验证限制在那条链上。任务换成支付状态、后台配置或异步任务时，应替换业务状态、权威材料、消费者与外部授权，不照抄账户状态中的名词。

Claude Code 提示词与 Codex Prompt 通常可以共用同一组目标、事实、范围和结果。两端各自加载项目规则、权限和 Skill，命令与工具可用性也可能不同；只有客户端差异确实改变执行时，才在对应会话补充。为两个客户端复制两份近似需求，会让目标和非目标逐渐漂移。

从首轮动作和软件结果检查 Prompt

Prompt 的质量不能从发送前的格式判断。先观察 Agent 的首轮动作：它是否读取适用规则和现状，是否区分需求事实与根因猜测，是否寻找产生状态的责任模块，是否只在缺少业务决定或授权时停下。首轮就按猜测编辑表面组件，通常说明目标来源或调查边界仍不清楚。

Agent 停止前，直接检查软件有没有达到 Prompt 写明的状态。局部界面缺陷应在目标视口消失且桌面对照保持；跨层状态应从生产者经过当前契约到达直接消费者；未获授权的提交、推送或外部写入不应发生。命令成功只能支持这些判断，不能替代它们。

首轮 Prompt 不必预测调查中出现的所有事实。OpenAI 的提示文档建议先用自己的话说明需求，再用后续消息调整结果；Claude Code 也允许在执行中中断或补充信息。新消息进入同一任务时，要说明它与旧要求的关系，否则“账户列表页也要显示”可能被理解为替换原有页面，“先别改权限”也可能只被当成暂时建议。

一条补充要求被团队确认为后续任务都要遵守的业务规则后，应在确认无冲突并获得规则写入授权后写回项目规则。会话里的更正只负责这次执行；长期规则仍需要自己的权威文件，不能靠恢复旧会话继续生效。

同一类任务连续需要追加相同背景时，先不要归因于模型记忆。长期事实应回到项目规则；带有相同判断分支的重复流程应进入 Skill；每次都必须发生的机械检查应进入 Hook 或 CI。当前 Prompt 只保留本次变化，这样修改项目规则、Skill 或 Hook 时，不必再同步一份大 Prompt。

Prompt 失效时先迁移内容

Prompt 过长时，先判断重复内容该由项目规则、Skill 还是 Hook 维护，不要先把原文压成更多缩写。每次都复制仓库地图和测试命令，说明项目规则缺失或没有加载；每次都描述同一研究、生成、审校流程，说明它应该进入 Skill；每次都要求“记得运行格式化”，说明机械动作没有进入 Hook 或现有工具链。

AI Coding 提示词越详细越好吗？ 不是。只保留会改变本次任务结果的信息；跨任务稳定的事实放进项目规则，重复流程放进 Skill，机械动作交给 Hook 或 CI，工具能力由权限策略限制。

给 Claude Code 或 Codex 写 Prompt 时必须列出文件路径吗？ 不必须。已知且权威的文件可以直接引用；路径未知时应说明责任边界、现象和结果，让 Agent 从项目规则、注册关系与调用链找到对应文件。

Claude Code 和 Codex 需要两套任务 Prompt 吗？ 通常不需要。目标、事实、范围和结果可以共用；客户端特有的命令、权限与扩展能力仍按各自配置和当前环境说明。

AI Coding 任务的完成标准怎么写？ 写用户、API、数据或进程能够观察到的状态，并说明必须保持不变的对照行为；测试命令是证据来源，不是软件结果本身。

下一次再写 AI Coding 提示词时，如果同一段流程已经在多个任务里重复，而且触发条件、输入边界、判断步骤和结果验证都稳定，就把它移进 Skill，让新的任务 Prompt 只提供本次输入。具体做法继续看《Agent Skill 怎么写：把重复工作流接入 Claude Code 与 Codex》。