写第一条 Prompt Spec

这一章只做一件事：把“给博客文章列表增加搜索”写成一条可以复制给 AI 编程工具的 Prompt Spec。你不需要先掌握所有 Seed 概念，先跑通一次小闭环。

Prompt Spec 的价值是减少猜测。它要让 AI 知道目标、路径、禁区、验收标准和验证命令。

训练任务

案例：博客文章列表已经能显示文章，现在要增加搜索输入框，按标题和摘要过滤文章。

这是一个适合第一次练习的任务，因为它有清楚的用户结果，也能用很少的命令验证。

复制这条 Prompt

把下面内容复制到 AI 执行会话，再把路径改成你的真实项目路径。

# 给博客文章列表增加搜索

## 背景
当前项目使用 MAWflow Seed 管理 AI Coding 协作。博客文章列表已经能展示文章，但用户不能按关键词搜索。请先读取项目入口、组件配置和博客模块相关文件，再修改。

## 目标
- 在博客文章列表增加一个搜索输入框。
- 搜索关键词同时匹配文章标题和摘要。
- 空关键词显示全部文章。
- 没有匹配结果时显示清楚的空状态。
- 不改变文章数据结构和后端接口。

## 允许修改
- code/client/**
- docs/modules/blog/**

## 禁止修改
- .local/**
- .maw/*.local.yaml
- 后端 API
- 发布配置
- 真实密钥、token、账号密码
- 与博客搜索无关的页面、模块或样式系统

## 验收标准
- 用户可以输入关键词并看到过滤结果。
- 清空关键词后恢复全部文章。
- 没有搜索结果时页面不空白，能说明当前无匹配内容。
- 如果改动影响模块说明，更新博客模块档案或说明原因。
- 最终说明包含变更、验证、风险、发布影响和下一步。

## 验证命令
- git diff --check
- npm run test:plan

## 收口要求
请用中文说明：
- 修改了哪些文件。
- 运行了哪些验证命令，结果如何。
- 是否需要发布才会生效。
- 是否有未覆盖的风险。

执行前改三处

复制前先把这三处改成你的项目事实：

要改的位置	怎么改
code/client/**	改成真实前端或页面源码路径。
docs/modules/blog/**	如果还没有博客模块档案，可以先改成 README 或相关 docs 路径。
npm run test:plan	如果项目没有 npm 命令面板，改成真实测试或检查命令。

不要把“允许修改”写成整个仓库。第一次练习越小，越容易看清 AI 是否按边界工作。

验收时看四件事

检查点	合格表现
行为	搜索、清空、无结果三个状态都能解释。
边界	没有碰后端、密钥、本机配置或无关组件。
验证	至少运行了 git diff --check 和项目测试计划入口。
收口	说明了变更、验证、风险、发布影响和下一步。

第一次收口模板

变更：
- 为博客文章列表增加搜索输入和无结果状态。

验证：
- git diff --check：通过 / 失败，原因是 ...
- npm run test:plan：通过 / 不适用，原因是 ...

风险：
- 目前只做前端本地过滤，未覆盖服务端搜索、分页和权限过滤。

发布影响：
- 命中 client 前端，需要部署前端后生效 / 只改文档，无需发布。

下一步：
- 如果要支持大量文章、分页或后端搜索，升级为 Task Pack。

常见错误

问题	修正方式
只写“帮我加搜索”	补上允许修改、禁止修改、验收和验证。
让 AI 猜路径	先读取 .maw/components.yaml 或自己填真实路径。
一上来做全站搜索	第一次只做博客列表局部搜索。
没有收口	要求 AI 说明变更、验证、风险和发布影响。

下一步

如果博客搜索开始涉及后端接口、分页、索引、权限、模块档案和发布验证，继续阅读 创建 Task Pack。