Prompt Spec

Prompt Spec 是 MAWflow Seed 推荐的 AI Coding 任务说明结构。它的目标不是把 prompt 写得更长，而是让 AI 明确知道：做什么、基于什么做、哪里能改、怎么证明完成。

适用对象：个人开发者、独立开发者、小团队负责人，以及需要把需求交给 AI 执行会话的人。

标准结构

# 任务标题

## 背景
说明产品目标、当前状态、用户口径和已确认边界。

## 目标
列出本次必须完成的行为变化或交付物。

## 输入资料
列出必须读取的文件、页面、接口、设计或任务包。

## 允许修改
- code/<app_key>/**
- docs/<topic>/**

## 禁止修改
- .local/**
- .maw/*.local.yaml
- 真实密钥 / token / 私钥
- 与任务无关的 code 组件

## 验收标准
- 用户可见行为。
- 文档或状态文件更新。
- 测试、构建或检查通过。

## 验证命令
列出推荐命令，不用“全仓随便跑”代替聚焦验证。

## 收口
要求说明变更、验证、发布影响、模块档案、任务状态和风险。

每个字段解决什么问题

字段	作用	如果缺失会怎样
背景	让 AI 理解当前项目状态和业务目标。	AI 容易按通用假设实现。
目标	固定本次必须完成的范围。	任务容易发散。
输入资料	限定事实源。	AI 可能读取过多无关文件，或漏读关键文件。
允许修改	给出可写边界。	AI 可能顺手改无关组件。
禁止修改	保护本机资料、密钥和无关业务代码。	容易造成泄露或无关变更。
验收标准	明确完成条件。	只能凭主观感觉判断完成。
验证命令	把完成状态转为证据。	修改无法复核。
收口	固定交付说明格式。	后续会话难以接上。

最小示例

# 为项目新增健康检查说明

## 背景
当前项目已有 README，但没有告诉 AI 修改后应该运行哪些检查。

## 目标
新增一段“本地验证”说明，列出 lint、测试和构建命令，并说明失败时如何记录。

## 输入资料
- README.md
- package.json

## 允许修改
- README.md

## 禁止修改
- code/**
- .local/**
- package-lock.json

## 验收标准
- README.md 有“本地验证”小节。
- 命令来自 package.json，不编造不存在的脚本。

## 验证命令
- git diff --check

## 收口
说明新增内容和验证结果。

编写原则

• 优先给项目事实，不给模糊愿望。
• 先写边界，再要求实现。
• 用仓库相对路径，不写本机绝对路径。
• 不把真实密钥、token、账号、客户资料或未脱敏日志贴进 prompt。
• 大任务拆成 Task Pack，不把所有工作压进一条长 prompt。
• 任务完成必须有证据：代码、测试、文档、状态或交付说明。

和 Task Pack 的关系

Prompt Spec 适合单次可完成的小任务。Task Pack 适合跨多步、可恢复、需要持续记录状态的复杂任务。Task Pack 里的每个编号任务仍应保持 Prompt Spec 的基本结构。

下一步阅读 Pack 类型。