规范文档
在写任何一行代码之前，先把这六份文档写掉
步骤越多，AI猜测越少
AI猜测越少，幻觉越少
-
PRD.md
产品需求
什么在范围内/什么明确不在
用户故事、成功标准
# PRD—Study Timer
## In Scope
- 番茄钟25/5、任务队列、每日统计
- 本地存储(LocalStorage)、无账号系统
## Out of Scope (v1)
- 云同步、团队协作、音效自定义
## Success Criteria
- 用户可30秒内完成第一个番茄
- 关掉浏览器再打开数据不丢
## User Stories
- 作为学生，我想...
- 作为... -
APP_FLOW.md
防止AI猜测用户如何移动——屏幕清单+路由+每一步决策点
用户流程
每个页面、每条路径
成功态/错误态、路由清单
# App Flow
## Screens
- / Home （进入按钮、今日统计）
- /timer Timer（开始/暂停/放弃）
- /stats Stats（7 日折线图）
## Flow: 开始一个番茄
1. Home→点击[开始]→/timer
2. /timer倒计时25:00→到0
3. 弹提示→计数+1→自动/break
## Error States
- 用户拒绝通知权限→顶部黄条提示
- 中途关闭→记录为“放弃” -
TECH_STACK.md
技术栈
每个包锁定版本号
消除幻觉依赖（React 18.2.0…）
# Tech Stack (LOCKED)
- Node 20.11.1
- Next.js 14.1.0
- React 18.2.0
- TypeScript 5.3.3
- Tailwind 3.4.1
- shadcn/ui 0.8.0
- Vitest 1.2.0
不允许引入UI库(MUI/Antd)或状态管理库(Redux/Zustand)，除非本文件更新过 -
FRONTEND_GUIDELINES.md
每个视觉决策都要锁定。“看起来好看”不是描述，"backdrop-filter: blur(12px)"才是
前端规范
色板、间距、圆角、排版
断点、组件命名、视觉令牌
# Design System
## Palette
primary #1D4ED8 danger #DC2626
ink #111827 dim #6B7280
bg #FFFFFF panel #F3F4F6
## Spacing scale (px)
4、8、12、16、24、32、48、64
## Radius/Shadow
radius-sm 4 、md 8 、lg 12
shadow-1 0 1 2 rgba(0,0,0,.06)
## Typography
Heading Inter 600、Body Inter 400
## Breakpoints
sm 640、md 768、lg 1024、xl 1280 -
BACKEND_STRUCTURE.md
后端结构
数据库模式、认证逻辑
API合约、存储、边缘情况
# Schema
## table: pomodoro
id TEXT PK
started_at INT NOT NULL # unix ms
duration INT DEFAULT 1500
status TEXT CHECK IN ('done','abort')
tag_id TEXT FK -> tag.id NULLABLE
## table: tag
id TEXT PK
name TEXT UNIQUE
color TEXT
## API
GET /api/stats?range=7d -> DailyStat[]
POST /api/pomodoro body: {duration,tag_id}
## Auth
无 (v1)、未来 magic-link + JWT -
IMPLEMENTATION_PLAN.md
让每次会话都能“从断点续跑”，AI不用重新猜项目在哪个阶段
实施计划
逐步序列1.1→1.2→…
步骤越多，AI猜测越少
# Build Order
1.1 pnpm create next-app@14.1.0 study-timer
1.2 安装tailwind/shadcn/vitest
1.3 建目录：app/components/lib/tests/
2.1 按FRONTEND_GUIDELINES建<Button>
2.2 建<TimerCircle>组件(SVG)
2.3 建<TagPicker>
3.1 按BACKEND_STRUCTURE建SQLite schema
3.2 lib/db.ts CRUD+Vitest单测
4.1 /timer页拼装、状态机
4.2 /stats页、折线图
5.1 集成e2e、pnpm test
会话持久层
-
CLAUDE.md
≤60行、每次自动读
- 技术栈摘要、命名约定
- 设计令牌、组件模式
- ”允许“与“禁止“清单
- 指向progress.txt/lessons.md
- 活文档：每次纠正就更新它
-
progress.txt
会话桥梁、断点续跑
- 已完成/进行中/接下来/已知Bug
- 每次功能完成后更新
- 新会话第一件事：读它
- 没有它→每次都从零上下文开始
- 有它→AI从断点精确继续
-
lessons.md
可选但强推、失败模式库
- 每次纠正AI后记录一条
- 格式：现象→原因→防止规则
- CLAUDE.md 里指向它，让AI每次读
- 这是把“好CLAUDE.md“与“伟大CLAUDE.md“分开的关键
- ≈Reflection模式的工程落地
Interrogation审问系统
先想清楚再动手
-
Prompt A：无尽审问（进入Plan Mode：Shift+Tab两次）
在写任何代码之前，在Planning模式下无尽地审问我的想法
不要假设任何问题。问问题直到没有假设剩下
一次只问一个问题，根据我的回答继续追问
直到你有95%的信心理解我的真实需求和目标，然后才给出方案
- Claude应该反问你的问题
- 给谁用？（用户画像）
- 核心动作是什么？
- 完成后发生什么？（成功态）
- 需要保存哪些数据？
- 需要展示哪些数据？
- 错误状态怎么处理？
- 需要登录吗？需要数据库吗？
- 需要在手机上工作吗？
- 离线场景要不要支持？
- 规矩
- 一次只问一个问题
- 根据你的回答继续追问
- 直到95%信心理解真实需求，才给方案
- 这些答案=六份规范文档的原材料
- 用户描述→PRD
- 数据结构→BACKEND STRUCTURE
- 流程→APP FLOW
- 手机需求→FRONTEND GUIDELINES
- 采访完开新会话执行（对话太长会污染上下文）
- Claude应该反问你的问题
-
Prompt B：审问结束后生成规范文档
基于我们的审问，生成规范文档：PRD.md、APP_FLOW.md、TECH_STACK.md、FRONTEND_GUIDELINES.md、BACKEND_STRUCTURE.md、IMPLEMENTATION_PLAN.md
要具体且详尽，没有歧义
Skill
一个Skill=一份“这类任务的操作手册”，可跨项目复用
Agent的程序性记忆
别写废话（重点写Gotchas）
用文件夹做渐进式披露
别绑死Agent，留灵活性
存脚本不重写、按需钩子、测量效果
-
好用Skill的四类信息
Anthropic内部9大类：API参考、产品验证、数据分析、业务流程、代码脚手架、质量Review、CI/CD、Runbook、基建运维
- 任务目标：这个Skill是干什么的
- 触发条件：什么时候用，什么时候不该用
- 执行步骤：推荐流程→检查顺序→分支
- 约束与坑点：Gotchas，只有你知道的经验
目录结构
（典型Skill是个“工作包”，不只SKILL.md）
my-skill/ |