从需求到交付的完整链路

请先帮我做需求拆解，不要立刻修改代码。
需求：
【这里写你的需求】
请按下面结构分析：
1. 背景是什么
 - 当前项目大概是什么
 - 为什么要做这个需求
 - 属于新功能、Bug 修复、UI 优化，还是重构
2. 要解决什么问题
 - 当前具体问题是什么
 - 本次要解决到什么程度
 - 哪些内容不是本次范围
3. 哪些文件可能相关
 - 请根据项目结构判断可能涉及哪些文件
 - 先列出来，不要直接修改
4. 哪些功能不能动
 - 不要改哪些逻辑
 - 不要动哪些接口
 - 不要影响哪些页面或组件
5. 什么结果算完成
 - 功能完成标准 / 页面完成标准 / 代码完成标准
6. 需要哪些测试
 - 需要运行什么命令
 - 需要手动检查哪些页面
 - 需要重点验证哪些流程
7. 有哪些风险
 - 可能影响哪些功能
 - 是否有样式污染风险
 - 是否有重构过度风险
 - 是否有新增依赖风险
最后，请给我一个简短的执行建议：
 - 建议先做哪一步
 - 是否需要我确认后再修改

先不要写代码，也不要修改任何文件。
请先根据当前需求和项目结构，制定一个修改计划。
等我确认后，再开始执行。

请开始小步实现。
当前只执行第【 1 】步：
【这里写本次只做的一个功能点】
要求：
1. 一次只改这个功能点
2. 只修改和当前功能直接相关的文件
3. 不要顺手重构无关代码
4. 不要修改目录结构
5. 不要新增不必要依赖
6. 不要删除已有功能
7. 不要改计划外的文件
修改完成后请停止，并输出：
1. 本次修改了哪些文件
2. 每个文件改了什么
3. 为什么这些修改是必要的
4. 有没有改到计划外内容
5. 有没有潜在风险
6. 下一步建议做什么
注意：
如果遇到不确定的地方，请先停下来问我，不要自行决定。

请对本次修改进行测试，不要继续新增功能。
请按下面顺序执行或说明：
1. 单元测试：项目是否有单元测试？有则运行；失败说明原因
2. 类型检查：是否有 typecheck 命令？有则运行；没有请说明
3. lint：运行 lint 检查，区分本次新增问题和项目原有问题
4. 构建：运行 build 命令；失败请说明报错原因和影响范围
5. 手动测试：列出需要手动测试的页面、用户操作步骤、每步预期结果
6. 浏览器测试：检查页面显示、控制台报错、移动端布局、关键按钮交互
7. 回归测试：检查本次修改是否影响旧功能，列出可能受影响的页面、组件和流程
最后请输出测试总结：
 - 哪些测试通过了 / 哪些失败了 / 失败原因是什么
 - 是否可以进入下一步 / 是否需要先修复问题

请对本次修改做代码审查，不要继续写代码。
请按下面结构审查：
1. Codex 自审：是否只改计划内文件 / 有无无关重构 / 有无新增依赖 / 有无硬编码 / 有无误删旧逻辑
2. 修改范围审查：改了哪些文件 / 每个文件为什么改 / 是否存在计划外修改 / 有无大面积无解释修改
3. 边界条件审查：空数据 / 接口失败 / 未登录 / 权限不足 / 重复点击 / 移动端异常
4. 安全问题审查：是否暴露密钥 token / 是否影响权限判断 / 是否缺输入校验 / 接口是否有鉴权
5. 删除内容审查：删了哪些代码 / 原因 / 是否确认无依赖 / 是否影响旧功能
6. 业务逻辑审查：是否符合需求 / 正常流程 / 异常流程 / 是否影响旧业务规则
7. 审查结论：可以继续 / 需要小修 / 需要回退部分修改 / 需要重新制定计划
注意：只审查，不要继续修改代码；若发现问题，先说明问题和建议，等我确认后再改。

feat: add user profile page        / feat: 新增用户资料页
fix: resolve login redirect issue   / fix: 修复登录后跳转异常
style: improve homepage responsive  / style: 优化首页移动端布局
refactor: simplify product card     / refactor: 简化产品卡片组件
docs: update setup guide            / docs: 更新项目使用说明

## 本次修改
- 优化首页首屏标题、副标题和 CTA 按钮
- 调整移动端首屏布局
- 保留原有跳转逻辑，没有修改接口和路由
## 测试结果
- npm run lint 通过
- npm run build 通过
- 手动检查首页桌面端和移动端显示正常
- 点击 CTA 按钮跳转正常
## 风险说明
- 本次涉及首页样式调整，需重点确认移动端显示
- 没有新增依赖
- 没有修改登录、接口、数据库逻辑

本次问题记录：
1. 问题：Codex 一开始想修改全局样式
   原因：需求里没有明确限制"只改首页"
   解决：补充提示词，要求只修改首页相关文件
2. 问题：移动端测试遗漏
   原因：计划阶段没有列移动端验收标准
   解决：以后在测试清单里固定加入移动端检查
3. 问题：PR 描述不够清楚
   原因：没有提前记录测试结果
   解决：每次测试后直接生成测试总结

## 工作规则
- 修改前必须先阅读项目结构
- 修改前必须先制定计划，不要直接写代码
- 一次只实现一个功能点
- 不要顺手重构无关代码
- 不要新增不必要依赖
- 不确定业务逻辑时，先提问，不要自行决定
## 测试要求
每次修改后至少检查：npm run lint / npm run build /
相关页面手动测试 / 浏览器控制台是否有报错 / 移动端布局是否正常
## 提交要求
提交前需要说明：修改了哪些文件 / 每个文件改了什么 /
测试是否通过 / 是否有风险或未完成事项

请进入提交与复盘阶段，不要继续新增功能。
请按下面结构输出：
1. Commit 建议：生成合适的 commit message，使用 conventional commit 格式，不要夸大范围
2. PR 描述：本次修改 / 修改原因 / 涉及文件 / 测试结果 / 风险说明 / reviewer 重点看哪里
3. 问题记录：复盘本次过程——遇到哪些问题、原因、如何解决、下次如何避免
4. Prompt 总结：哪些 Prompt 有效、为什么有效、适合什么场景复用、是否建议加入 AGENTS.md
5. AGENTS.md 更新建议：适合加入的长期规则（修改前 / 修改中 / 测试 / 提交）
6. 项目文档更新建议：是否需要更新 README.md / .env.example / docs/ / CHANGELOG.md
最后请给出交付结论：是否可以提交 / 是否可以发 PR / 是否有未完成事项 / 是否有需人工确认的风险

把目前的进度整理成一份 HANDOFF.md，包含：当前进度、待办事项、
已知约束、下一步计划。保存到项目根目录。

先读 HANDOFF.md，然后继续推进任务。

# Handoff — [项目名称] — [日期]
## 当前进度
- [具体描述：做到了什么]
## 待办事项
- [ ] [下一个具体任务]
- [ ] [其他待办]
## 已知约束
- [比如：JWT 认证 / AUTH_SECRET 必须设置 / PostgreSQL]
## 下一步计划
1. [第一步具体操作]
2. [第二步具体操作]
## 踩过的坑（可选）
- [记录防止重蹈覆辙]

请先不要修改任何代码。
请阅读当前项目，并输出一份项目理解报告，包括：
1. 技术栈（前端/后端/数据库/构建工具，是否用 TypeScript、Tailwind、框架）
2. 目录结构（页面、组件、工具函数、接口、配置文件分别在哪；哪些目录是核心）
3. 启动方式（如何安装依赖、本地启动、是否需要环境变量）
4. 测试命令（test / lint / typecheck / build，没有请说明）
5. 核心模块（核心功能模块分别负责什么，改功能优先看哪些文件）
6. 后续修改风险（哪些文件/目录改动风险高、哪些逻辑不能随便改）
请只输出项目理解报告，不要修改代码。输出完成后等待我确认。

我遇到一个 bug：
【现象】
【复现步骤】
【期望结果】
【实际结果】
【相关文件/页面】
请先定位原因，不要直接修改。先给出：
1. 可能原因 2. 需要查看的文件 3. 修复方案 4. 风险点
等我确认后再改代码。

我想新增一个功能：
【功能描述】【入口位置】【交互流程】【视觉要求】
【数据来源】【验收标准】
请先阅读相关代码，给出实现计划。不要改无关文件。
实现后请运行测试并总结 diff。

请根据下面要求实现一个页面：
【页面用途】【目标用户】【视觉风格】【模块结构】
【中文文案】【响应式要求】【不要出现的问题】
请先给出组件拆分方案，再开始实现。

请审查当前分支相对 main 的 diff。重点检查：
1. 潜在 bug 2. 边界条件 3. 安全风险
4. 类型问题 5. 性能问题 6. 是否有无关修改 7. 测试是否充分
请不要直接修改代码，先输出 review 报告。

# 重构模板
请重构以下模块：【模块路径】
目标：1. 提高可读性 2. 减少重复代码 3. 保持现有行为不变
4. 不改变公共 API 5. 不引入新依赖
请先写重构计划，并说明如何验证行为一致。

# 写测试模板
请为以下功能补充测试：【功能描述】【相关文件】【边界情况】
要求：1. 不改业务逻辑 2. 覆盖正常路径 3. 覆盖异常路径
4. 覆盖边界条件 5. 运行测试并报告结果。

# 写文档模板
请根据当前项目生成文档：
1. 项目简介 2. 安装方式 3. 启动方式 4. 环境变量说明
5. 常用命令 6. 目录结构 7. 开发注意事项 8. 常见问题
请不要编造不存在的命令，必须基于项目文件判断。

请先阅读这个仓库的目录结构、README、包管理器配置和测试配置。
不要修改文件。请总结：
1. 项目用途
2. 主要技术栈
3. 如何安装依赖和运行测试
4. 你建议我下一步交给你的 3 个低风险任务

请修复当前仓库中最小范围的一个测试失败。
要求：
1. 先运行测试，确认失败信息。
2. 阅读相关代码和测试，不做无关重构。
3. 修改最少必要文件。
4. 修复后重新运行相关测试。
5. 最后总结：失败原因、改了哪些文件、验证命令和剩余风险。

请更新 [文档文件] 中关于 [主题] 的说明。
要求：
1. 先读取相关官方资料和现有文档结构。
2. 保持中文教程风格，避免整段翻译官方原文。
3. 涉及操作步骤时添加截图占位。
4. 修改后运行文档站构建。
5. 最后列出来源链接和需要人工补图的位置。

git diff

请 review 你刚才的改动，不要继续修改文件。
请重点检查：
1. 是否有无关改动
2. 是否遗漏测试
3. 是否引入安全或兼容风险
4. 是否还有未验证的地方

请用提交前摘要格式输出：
- 改动目标
- 修改文件
- 验证命令
- 验证结果
- 剩余风险
- 建议 commit message

git add .
git commit -m "fix: resolve failing test"