Codex 高效开发协作手册

这份文档的目标不是让需求写得更长，而是让每次任务更快进入正确执行路径。核心原则是：用模式替代长篇解释，用禁区约束风险，用验收定义完成，用证据减少猜测。

1. 现有系统能力

1.1 Codex 本地工程能力

Codex 在当前环境里不是单纯聊天助手，而是一个本地工程执行系统，主要能力包括：

读取和搜索本地仓库：适合定位代码路径、依赖关系、配置、测试、历史上下文。
修改文件：适合做小范围代码变更、补测试、改脚本、整理文档。
执行命令：适合跑 uv run、pytest、编译检查、服务启动、日志/进程检查。
使用记忆：适合复用你以前确认过的规则，例如"只做新增""生产数据先只读""prompt 规则就近放置"。
使用浏览器插件：适合前端、页面、交互、localhost 验证，尤其是改完 UI 后截图检查。
使用 MCP/文档查询：适合查第三方库、OpenAI/Codex、框架官方文档，避免靠过期记忆。
使用 Skills：适合把固定工作流变成可复用规程，例如 Python 工程规范、文档、表格、PPT、图片生成等。
使用线程/分支能力：适合把复杂任务拆到多个工作流里，或者让不同任务保持隔离。

1.2 当前可用插件和 Skill

你当前环境里比较重要的能力可以这样理解：

Browser：用于打开、点击、截图、验证本地页面或 localhost。
Documents：用于创建和编辑 Word/docx 文档。
Presentations：用于制作 PPT。
Spreadsheets：用于处理 Excel/CSV/表格。
Figma：用于设计稿和前端实现相关工作。
Superpowers：用于更结构化的计划、调试、TDD、协作流程。
python-coding-standards：用于 Python 代码设计、模块边界、抽象取舍、避免过度工程。
openai-docs：用于 OpenAI、Codex、API、模型选择等官方文档问题。
imagegen：用于生成或编辑位图图片。

1.3 Skill、MCP、插件、模式的区别

这几个概念容易混，但可以用下面的方式区分：

Mode：协作节奏。决定"先盘点、直接改、团队分工、只做 review、只读证据"等。
Skill：工作规程。决定"如何做"，比如 Python 怎么写、文档怎么验、表格怎么处理。
MCP：外部知识或能力入口。决定"去哪里查"或"调用哪个外部能力"。
Plugin：一组 Skill、MCP、应用能力的组合包。

一句话：Mode 负责节奏，Skill 负责方法，MCP 负责外部能力，Plugin 负责能力集合。

2. 你的现有全局规则和项目规则

2.1 通用协作规则

遇到不确定的代码设计问题，必须先问，不能直接行动。
不能写兼容性代码，除非你主动要求。
任务明确时应该直接执行，不要停在建议。
复杂行为、路由、prompt、生产数据类任务，先盘点再列计划更稳。

2.3 你长期偏好的工程约束

能只新增就不要改旧入口。
能局部规则就不要塞全局 prompt。
能结构化字段判断就不要从大段文本里模糊匹配。
能给原始数据证据就不要只给口头推断。
能跑定向测试就不要只说"理论上可以"。
前端可见才算完成的任务，不能只停在后端生成或 CSV 产出。
生产数据问题先只读排查，再给修复 SQL 或脚本。
prompt、路由、数据源规则要同时体现在运行时逻辑、prompt 文本和测试里。
多对象比较时，缺失数据必须对象局部处理，不能跨对象推断。

3. 推荐协作模式

3.1 驾驶模式

用途：小 bug、小接口、小脚本、小范围字段或 UI 调整。

特点：你给目标、禁区、验收，Codex 直接执行。只有遇到不确定设计问题才问你。

适合：

明确知道要改哪里。
风险范围小。
不涉及生产数据写入。
不涉及大范围 prompt 或路由变化。

不适合：

需求本身还在探索。
需要产品判断。
需要跨模块重构。

3.2 侦察模式

用途：先让 Codex 读代码、盘路径、找风险、列最小修改计划。

特点：只读，不改。适合你不想一开始写很长需求时，用代码反向建模。

适合：

志愿助手路由。
prompt 行为调整。
数据源加载规则。
异步任务链路。
权限、SSE、接口流转。
不确定问题到底在哪个模块。

输出应该包括：

关键代码路径。
当前行为链路。
风险点。
最小修改方案。
需要你确认的设计问题。

3.3 团队模式

用途：复杂任务需要多角度快速拆解。

特点：模拟多角色并行思考，最后统一汇总成计划。

推荐角色：

路径侦察员：找代码入口、调用链、配置、测试。
证据分析员：查 DB、日志、原始 JSON、复现输出。
实现工程师：给最小改法。
Reviewer：挑风险、边界、漏测、回归点。

适合：

多链路问题。
产品规则 + prompt + 数据源 + 测试同时变化。
线上问题不明确。
改动范围可能扩大，需要先控边界。

3.4 证据模式

用途：生产数据、DB、OCR、AI 数据链路、指标异常。

特点：只读优先，结论必须绑定证据。

输出应该包括：

代码路径。
表/模型/字段。
原始查询结果或日志片段。
根因。
修复 SQL 或脚本草案。
写入前需要你确认的风险。

3.5 审查模式

用途：你已经有改动，需要 Codex 找 bug 和风险。

特点：像 code review 一样，问题优先，不主动重构。

输出应该包括：

严重问题。
文件和行号。
行为风险。
缺失测试。
是否建议继续改。

3.6 前端验证模式

用途：ry-pc、ry-app、页面交互、样式、可视化功能。

特点：修改后必须通过浏览器或截图验证，不只看代码。

适合：

页面布局。
按钮/表单/弹窗。
本地 localhost。
前端状态展示。
视觉重叠、响应式、交互异常。

3.7 文档/表格/材料模式

用途：Word、PPT、Excel、CSV、说明文档。

特点：直接触发对应 Skill 或插件，不用当普通文本任务处理。

适合：

.docx：Documents。
.pptx：Presentations。
.xlsx / .csv：Spreadsheets。
普通 .md：直接生成 Markdown。

4. 任务应该如何选择模式

4.1 可以直接驾驶的情况

使用驾驶模式：

"这个字段返回错了，按现有字段改回来。"
"新增一个很小的异步接口。"
"把脚本参数加一个过滤条件。"
"修一个明确的测试失败。"
"页面这里按钮文案改掉，并跑一下页面。"

推荐表达：

text 复制代码

驾驶模式：
目标：
禁区：
验收：
遇到设计不确定再问我。

4.2 必须先侦察的情况

使用侦察模式：

"这个功能为什么没走预期分支？"
"这个 prompt 为什么输出不对？"
"这个接口数据到底来自哪里？"
"这个生产任务为什么没跑起来？"
"这个规则应该加在哪里最合适？"

推荐表达：

text 复制代码

侦察模式：
问题：
范围：
先不要改代码。
输出代码路径、当前行为、风险点、最小修改计划。

4.3 适合团队模式的情况

使用团队模式：

"一个问题涉及接口、DB、prompt、前端展示。"
"我要加一个新业务分支，但不能破坏旧逻辑。"
"线上现象复杂，需要同时查代码和数据。"
"我怀疑实现方向错了，需要先推演。"

推荐表达：

text 复制代码

团队模式：
目标：
分角色盘点：代码路径 / 数据证据 / 最小实现 / review 风险。
先不改代码，最后给执行计划。

4.4 必须证据优先的情况

使用证据模式：

生产 DB 行为异常。
指标、报表、OCR、AI 衍生数据不一致。
要给修复 SQL。
要解释为什么某条数据错了。

推荐表达：

text 复制代码

证据模式：
现象：
只读排查。
必须给表、字段、原始记录、代码路径、根因。
修复 SQL 先给草案，不要执行。

4.5 适合审查模式的情况

使用审查模式：

"帮我 review 这个 diff。"
"看这次改动有没有回归风险。"
"不要改，只指出问题。"

推荐表达：

text 复制代码

审查模式：
范围：
只找 bug、风险、缺失测试。
不要重构，不要顺手改。

5. 关键 Prompt 模板

5.1 最快通用模板

text 复制代码

驾驶模式：
目标：
禁区：
验收：
遇到不确定的代码设计问题先问 JiaSen。

5.2 复杂后端改动模板

text 复制代码

侦察模式：
问题/目标：
范围：ry-server / 具体 app 或接口
要求：
1. 先读代码，不改代码
2. 给出入口、调用链、相关模型/表、已有测试
3. 给出最小修改计划
4. 标出需要 JiaSen 确认的设计点

5.3 新增 ry-server 异步接口模板

text 复制代码

驾驶模式：
目标：新增 XXX 接口
禁区：
- 不要在同步 app 里新增接口
- 不要改旧接口行为
- 不写兼容性代码
硬规则：
- 放在 async_* 应用
- async def
- Django 异步 ORM
- 注册到对应 async router
- URL 前缀 /api/async/
- 响应用 ry_common_response，成功 GSuccess，失败 Error
验收：
- 增加/更新定向测试
- 跑对应 pytest 或 py_compile

5.4 Prompt 或志愿助手规则调整模板

text 复制代码

侦察模式：
目标：
范围：async_ai / volunteer / prompt / 数据源
先不要改。
请输出：
1. 当前意图识别和数据源加载链路
2. prompt 拼接位置
3. 规则应该放在运行时逻辑、prompt、测试里的哪个位置
4. 最小修改计划
约束：
- 局部规则就近放置，不要加到全局 prompt
- 优先使用结构化字段，不要从大段 raw text 模糊匹配
- 多对象数据缺失不能跨对象推断

5.5 生产数据排查模板

text 复制代码

证据模式：
现象：
范围：
只读排查，不要写库。
要求：
1. 加载正确 env
2. 通过 Django/只读事务查数据
3. 给出表、字段、原始记录
4. 给出代码路径和根因
5. 给修复 SQL 草案，但不要执行

5.6 AI 衍生数据生成/发布模板

text 复制代码

团队模式：
目标：
范围：apps/scripts/ai_derivative_data_update
要求：
1. 先确认生成脚本、参数、去重 key、输出 CSV
2. 再确认前端可见数据层如何更新
3. 给出预检数量和最终更新数量
4. 生成完成不算完成，前端可见数据更新才算完成
禁区：
- 不要改旧 builder，除非我确认
- 能新增 wrapper 就新增 wrapper

5.7 前端页面修改模板

text 复制代码

驾驶模式：
目标：
范围：ry-pc / ry-app
禁区：
验收：
- 改完启动本地服务或使用现有服务
- 用 Browser 打开页面
- 截图检查布局、交互、文字是否重叠
注意：
- ry-app 是 uniapp-x，不要使用 Object.keys，使用 UTSJSONObject.keys(obj)

5.8 Review 模板

text 复制代码

审查模式：
范围：
只 review，不改代码。
优先级：
1. 行为 bug
2. 回归风险
3. 数据/权限/异步问题
4. 缺失测试
请给文件和行号。

5.9 "只新增"模板

text 复制代码

驾驶模式：
目标：
强约束：
- 只新增，不改原入口
- 不重构底层函数
- 不写兼容性代码
- 如必须改旧代码，先停下来问 JiaSen
验收：

5.10 快速定位数据来源模板

text 复制代码

侦察模式：
问题：这个字段/指标/文案从哪里来？
输出格式：
table/model -> field -> context path -> 使用位置
要求：
- 只回答当前问题范围
- 不要展开相邻主题
- 如果有 raw JSON，请给原始路径

6. 默认触发矩阵

以后可以按下面规则自动触发：

任务类型	推荐模式	推荐能力
小 bug / 小脚本 / 小字段	驾驶模式	rg + 代码修改 + 定向测试
新增后端接口	驾驶模式	async_* 规则 + pytest/py_compile
prompt / 路由 / 数据源	侦察模式	代码路径 + prompt 位置 + 测试计划
生产 DB / 指标异常	证据模式	env + Django 只读查询 + SQL 草案
多链路复杂需求	团队模式	分角色盘点 + 汇总计划
前端页面	前端验证模式	Browser + 截图
文档 / PPT / Excel	文档材料模式	Documents / Presentations / Spreadsheets
第三方库最新用法	查询模式	Context7 / 官方文档
OpenAI / Codex 问题	查询模式	openai-docs
已有 diff 检查	审查模式	code review 风格输出

7. 推荐的默认开发协议

你可以把下面作为默认工作协议：

text 复制代码

默认协议：
1. 普通明确任务：驾驶模式，直接执行。
2. 涉及 prompt、路由、数据源、生产数据：先侦察或证据模式。
3. 涉及多模块复杂改动：团队模式。
4. 遇到不确定代码设计问题：先问 JiaSen。
5. 不写兼容性代码，除非 JiaSen 主动要求。
6. 能只新增就只新增。
7. 改完要给验证命令和结果。

8. 一句话启动命令

日常最快可以只发这些：

text 复制代码

#drive
目标：
禁区：
验收：

text 复制代码

#recon
问题：
范围：
先不要改，给路径、风险、计划。

text 复制代码

#team
目标：
分角色盘点，最后给最小执行计划，先不改。

text 复制代码

#evidence
现象：
只读排查，给代码路径、表字段、原始证据、修复草案。

text 复制代码

#review
范围：
只找 bug 和风险，不改代码。

9. 最实用的结论

你的效率瓶颈不主要是"需求没一次性想清楚"，而是复杂任务没有先切换协作模式。

更快的工作方式是：

先选模式。
再给目标。
明确禁区。
定义验收。
让 Codex 侦察、执行、验证。

你不需要把所有细节一次性写完。对于复杂系统，先让 Codex 读代码反向建模，往往比你提前写完整需求更快、更准。

JiaSen 的 Codex 效率跃迁落地方案

版本：2026-06-06

这份文档不是"更快路由手册"，而是一个可执行的开发体系。目标是把一次需求从聊天式沟通升级为：

text 复制代码

材料输入 -> 需求规格书 -> 技术计划 -> 验收矩阵 -> 执行开发 -> 证据验收 -> 复盘沉淀

Plan 模式之所以提效，是因为它把"边聊边改"变成"确认后执行"。下一阶段要继续大幅提效，需要把 PRD、飞书、Figma、截图、日志、代码侦察都纳入同一个可确认的开发契约。

1. 核心判断

你的效率瓶颈不只是需求描述问题，而是当前工作流缺少三个上游产物：

需求规格书：确认到底做什么、不做什么。
设计映射表：确认页面、组件、状态、交互来自哪里。
验收矩阵：确认每个需求点如何证明完成。

普通 Plan 模式只解决"怎么做"。如果没有前置规格书，Plan 很容易建立在模糊需求上；如果没有验收矩阵，执行完还要反复确认"这样算不算完成"。

更高效的结构是：

text 复制代码

PRD/飞书/Figma/截图/现象
  -> Codex 整理需求规格书
  -> JiaSen 确认
  -> Codex 读代码校验可落地性
  -> Codex 输出技术计划
  -> JiaSen 确认关键设计
  -> Codex 执行
  -> Codex 按验收矩阵逐项验证

2. 现有能力与接入边界

2.1 当前确定可用的能力

本地代码搜索：用 rg 快速定位入口、调用链、测试、配置。
本地文件修改：可以直接改代码、补测试、写脚本、生成文档。
命令执行：可以跑 uv run、pytest、编译检查、服务、日志和进程检查。
Browser 插件：可以打开 localhost、点击、截图、验证前端页面。
Documents / Spreadsheets / Presentations：可以处理 Word、Excel/CSV、PPT。
Context7：可以查询第三方库官方文档。
openai-docs：可以查询 OpenAI / Codex 官方文档。
记忆：可以复用你的项目偏好和历史决策。
线程工具：可以创建、fork、发送消息到其他 Codex 线程，做真正的多线程分工。

2.2 Figma 和飞书的现实接入方式

当前线程里没有直接暴露"读取飞书文档"或"读取 Figma 设计稿"的可调用工具。因此落地要分三档：

A 档：手动材料包，马上可用

你把材料复制或导出后交给 Codex：

飞书 PRD：复制正文、导出 Markdown、导出 PDF、截图。
Figma：给截图、页面说明、关键帧截图、组件状态截图、标注图。
接口文档：复制文本、Markdown、OpenAPI JSON、截图。
线上现象：截图、日志、请求响应、DB 记录。

优点：马上能用，不依赖额外接入。

B 档：文件化材料包，强烈推荐

把一个需求的材料统一放到一个目录：

text 复制代码

/Users/zhangjiasen/Downloads/codex_feature_packets/2026-06-06-feature-name/
  00_raw/
    prd.md
    feishu-export.pdf
    figma-screen-01.png
    api.md
    logs.txt
  01_spec.md
  02_design_mapping.md
  03_tech_plan.md
  04_acceptance_matrix.md
  05_execution_log.md

优点：可暂停、可恢复、可复盘、可交给另一个线程。

C 档：插件/连接器直连，后续增强

如果后续 Figma 或飞书连接器可用，可以把"手动材料输入"替换成"工具读取"。但工作流不变：

text 复制代码

工具读取材料 -> 规格书 -> 计划 -> 验收矩阵 -> 执行

这点很重要：真正提效的是流程契约，不是单纯接入工具。

3. 效率跃迁的 6 层架构

3.1 输入层：统一材料包

目标：不要让需求散落在聊天、截图、文档、设计稿、日志里。

输入材料建议分成：

PRD：业务背景、用户场景、功能范围。
飞书：产品规则、评审意见、补充说明。
Figma：页面布局、组件状态、交互细节。
接口文档：请求参数、响应结构、错误码。
数据证据：DB 记录、CSV、日志、原始 JSON。
现象材料：截图、录屏、复现步骤。

Codex 的第一步不是写代码，而是把材料整理为规格书。

3.2 规格层：需求规格书

目标：把模糊需求变成可确认的产品契约。

规格书必须包含：

背景：为什么做。
目标：这次要解决什么。
非目标：这次明确不做什么。
用户路径：用户怎么触发、看到什么。
数据来源：数据来自哪个接口、表、字段、脚本或 prompt。
业务规则：必须遵守的规则。
边界场景：空数据、异常、权限、重复、并发、历史数据。
待确认问题：需要 JiaSen 决策的地方。

3.3 设计层：Figma/页面映射表

目标：把设计稿变成可开发清单。

映射表必须包含：

页面名称。
组件名称。
状态：默认、加载中、空数据、错误、禁用、选中。
交互：点击、输入、提交、刷新、跳转。
数据绑定：字段来自哪里。
与现有组件的关系：复用、扩展、新增。
验证方式：Browser 截图、交互操作、响应式检查。

3.4 计划层：技术执行计划

目标：把规格书映射到具体代码改动。

计划必须包含：

代码入口。
调用链。
修改文件。
新增文件。
测试文件。
运行命令。
风险点。
需要确认的设计问题。

3.5 验收层：验收矩阵

目标：让完成标准可检查，减少改完后的反复确认。

验收矩阵格式：

text 复制代码

需求点 | 实现位置 | 验证方式 | 通过标准 | 状态

例子：

text 复制代码

新增异步接口 | apps/async_xxx/api.py | pytest 指定测试 | 返回 GSuccess 且结构正确 | 待验证
页面展示字段 | ry-pc xxx.vue | Browser 截图 | 字段展示且无重叠 | 待验证
数据写入前端可见层 | EnrollProfGroup.profession_detail_list | Django 只读查询 | 目标 group 已更新 | 待验证
prompt 局部规则 | volunteer_ai_major_prompt.py | prompt 单测 | 规则出现在对应数据块旁 | 待验证

3.6 执行层：开发、测试、证据

目标：只按确认后的计划执行。

执行原则：

不确定设计先问我。
不写兼容性代码，除非我主动要求。
能只新增就只新增。
生产数据先只读。
前端改动必须截图验证。
后端接口必须跑定向测试或编译检查。
prompt/路由/数据源规则要同时锁在代码、prompt、测试里。

4. 具体可执行工作流

4.1 普通小任务：目标驱动开发流

适合：小 bug、小字段、小脚本、小接口。

流程：

text 复制代码

JiaSen 给目标、禁区、验收
  -> Codex 快速读代码
  -> Codex 直接改
  -> Codex 跑定向验证
  -> Codex 输出结果

启动 Prompt：

text 复制代码

驾驶模式：
目标：
禁区：
验收：
遇到不确定的代码设计问题先问 JiaSen。

4.2 中型需求：规格书优先开发流

适合：功能新增、PRD 需求、接口 + 页面、业务规则变化。

流程：

text 复制代码

JiaSen 提供 PRD/飞书/截图
  -> Codex 整理需求规格书
  -> JiaSen 确认规格
  -> Codex 读代码
  -> Codex 输出技术计划和验收矩阵
  -> JiaSen 确认计划
  -> Codex 实现
  -> Codex 按矩阵验证

启动 Prompt：

text 复制代码

规格书优先模式：
我会提供 PRD/飞书/截图/补充说明。
先不要写代码。
请先输出：
1. 需求规格书
2. 非目标
3. 业务规则
4. 边界场景
5. 待确认问题
6. 初版验收矩阵
我确认后，再进入代码侦察和技术计划。

4.3 PRD + Figma：设计驱动开发流

适合：ry-pc 页面、ry-app 页面、组件状态、交互功能。

流程：

text 复制代码

PRD/飞书 -> 需求规格书
Figma/截图 -> 页面映射表
代码侦察 -> 技术计划
确认 -> 开发
Browser -> 截图/交互验收

启动 Prompt：

text 复制代码

PRD + Figma 模式：
我会提供 PRD 文本和 Figma 截图/链接/导出图。
先不要写代码。
请输出：
1. 需求规格书
2. 页面结构拆解
3. 组件与状态清单
4. 数据字段映射
5. 与现有页面/组件的复用判断
6. 待确认问题
7. 验收矩阵
确认后再读代码并输出技术计划。

4.4 复杂后端：侦察 + 计划 + 执行流

适合：ry-server、async_ai、prompt、路由、数据源、异步任务。

流程：

text 复制代码

先只读侦察
  -> 输出代码路径、调用链、当前行为
  -> 输出最小修改方案
  -> JiaSen 确认
  -> 执行
  -> 定向测试

启动 Prompt：

text 复制代码

后端侦察模式：
目标/问题：
范围：
先不要改代码。
请输出：
1. 入口和调用链
2. 相关模型/表/字段
3. 当前行为
4. 风险点
5. 最小修改计划
6. 需要 JiaSen 确认的设计问题

4.5 生产问题：证据优先流

适合：线上数据、报表、OCR、AI 衍生数据、DB 修复。

流程：

text 复制代码

只读排查
  -> 表/字段/原始记录
  -> 代码路径
  -> 根因
  -> 修复 SQL 草案
  -> JiaSen 确认后执行

启动 Prompt：

text 复制代码

证据模式：
现象：
范围：
只读排查，不要写库。
必须输出：
1. 代码路径
2. 表/模型/字段
3. 原始记录或日志
4. 根因
5. 修复 SQL/脚本草案
6. 执行风险和回滚建议

4.6 多链路大任务：真实团队模式

适合：一个任务同时涉及 PRD、Figma、后端、前端、DB、prompt、测试。

流程：

text 复制代码

主线程：任务总控和最终决策
子线程 A：PRD/规则整理
子线程 B：代码路径侦察
子线程 C：设计稿/页面映射
子线程 D：测试和风险 review
主线程汇总：规格书 + 技术计划 + 验收矩阵
JiaSen 确认后执行

启动 Prompt：

text 复制代码

真实团队模式：
目标：
材料：
请将任务拆成多个角色：
1. PRD 分析
2. 代码侦察
3. 设计映射
4. 测试与风险 review
先不要改代码。
如需要，可以创建/分配子线程。
最后汇总成：
- 需求规格书
- 技术计划
- 验收矩阵
- 待确认问题

5. 推荐的"需求材料包"标准

每个中大型任务建议先形成一个材料包。

目录模板：

text 复制代码

/Users/zhangjiasen/Downloads/codex_feature_packets/YYYY-MM-DD-topic/
  00_raw/
    prd.md
    feishu.md
    figma/
      screen-01.png
      screen-02.png
    api.md
    logs.txt
    data_sample.json
  01_spec.md
  02_design_mapping.md
  03_code_recon.md
  04_tech_plan.md
  05_acceptance_matrix.md
  06_execution_log.md
  07_review.md

材料包里的关键文件含义：

00_raw/：原始材料，不整理也可以先放进去。
01_spec.md：需求规格书，JiaSen 确认后进入开发。
02_design_mapping.md：Figma/页面映射。
03_code_recon.md：代码侦察结果。
04_tech_plan.md：技术计划。
05_acceptance_matrix.md：验收矩阵。
06_execution_log.md：执行命令、结果、变更摘要。
07_review.md：风险和后续建议。

6. 关键产物模板

6.1 需求规格书模板

markdown 复制代码

# 需求规格书

## 背景

## 目标

## 非目标

## 用户场景

## 功能范围

## 业务规则

## 数据来源

| 数据 | 来源 | 字段/路径 | 备注 |
| --- | --- | --- | --- |

## 页面/接口变化

## 边界场景

## 待确认问题

## 初版验收标准

6.2 设计映射表模板

markdown 复制代码

# 设计映射表

## 页面

## 组件清单

| 组件 | 状态 | 数据来源 | 交互 | 复用/新增 |
| --- | --- | --- | --- | --- |

## 页面状态

| 状态 | 展示 | 触发条件 | 验证方式 |
| --- | --- | --- | --- |

## 响应式/端差异

## 待确认设计问题

6.3 技术计划模板

markdown 复制代码

# 技术计划

## 代码入口

## 调用链

## 修改文件

## 新增文件

## 数据模型/接口影响

## 测试计划

## 风险点

## 需要 我 确认的问题

6.4 验收矩阵模板

markdown 复制代码

# 验收矩阵

| 需求点 | 实现位置 | 验证方式 | 通过标准 | 状态 |
| --- | --- | --- | --- | --- |
|  |  |  |  | 待验证 |

6.5 执行日志模板

markdown 复制代码

# 执行日志

## 变更摘要

## 执行命令

| 命令 | 结果 | 备注 |
| --- | --- | --- |

## 验收结果

## 未完成/风险

7. 项目专属执行规则

7.1 ry-server 新增接口

必须遵守：

新增接口放在 async_* 应用。
使用 async def。
使用 Django 异步 ORM，例如 afirst、acount、aexists、acreate、asave、adelete、async for。
注册到对应异步 router，例如 async_ai_router。
URL 前缀为 /api/async/。
禁止在同步应用新增接口。
响应结构用 ry_common_response。
成功响应使用 GSuccess。
失败响应使用 Error。
执行前加载正确 env。

专用 Prompt：

text 复制代码

新增 ry-server 异步接口：
目标：
范围：
禁区：
- 不要在同步 app 新增接口
- 不要改旧接口行为
- 不写兼容性代码
硬规则：
- async_* 应用
- async def
- Django 异步 ORM
- async router
- /api/async/
- ry_common_response + GSuccess/Error
验收：
- 定向测试或 py_compile
- 给出接口路径和响应结构

7.2 ry-app uniapp-x

必须遵守：

不使用 Object.keys。
获取对象键列表使用 UTSJSONObject.keys(obj)。

专用 Prompt：

text 复制代码

ry-app 修改：
目标：
范围：
注意：
- uniapp-x 环境
- 不要使用 Object.keys
- 对象 keys 使用 UTSJSONObject.keys(obj)
验收：

7.3 prompt / 志愿助手

必须遵守：

先侦察，不要直接改。
规则尽量就近放在相关数据块旁。
不把局部规则塞进全局 prompt。
优先结构化字段，不从大段 raw text 模糊匹配。
多对象比较时，不能跨对象推断缺失对象的数据。
运行时逻辑、prompt 文本、测试三者要对齐。

专用 Prompt：

text 复制代码

志愿助手/prompt 侦察：
目标：
范围：
先不要改代码。
请输出：
1. 意图识别链路
2. 数据源加载链路
3. prompt 拼接位置
4. 结构化字段来源
5. 应该改运行时逻辑、prompt、测试的哪些点
约束：
- 局部规则就近放置
- 不加到全局 prompt
- 不从 raw text 模糊匹配
- 不跨对象推断

7.4 AI 衍生数据

必须遵守：

后端生成不等于完成。
CSV/脚本生成后，要确认前端可见数据层是否更新。
只新增 wrapper 优先，不动旧 builder。
预检数量和最终更新数量要对得上。

专用 Prompt：

text 复制代码

AI 衍生数据任务：
目标：
范围：
要求：
1. 先确认生成脚本、参数、去重 key、输出位置
2. 再确认前端可见数据层
3. 给预检数量和最终更新数量
4. 生成完成不算完成，前端可见才算完成
禁区：
- 不改旧 builder，除非 JiaSen 确认
- 能新增 wrapper 就新增 wrapper

8. 一次真实需求的推荐执行顺序

假设你有一个新功能，来自飞书 PRD 和 Figma 页面。

推荐你这样发第一条消息：

text 复制代码

规格书优先 + PRD/Figma 模式：
我会提供飞书 PRD 文本和 Figma 截图。
先不要写代码。
第一步只做材料整理，输出：
1. 需求规格书
2. 页面/组件/状态映射表
3. 初版验收矩阵
4. 待确认问题

你确认后，第二条消息：

text 复制代码

进入代码侦察：
根据已确认的规格书和设计映射，读取代码。
先不要改。
输出：
1. 代码入口和调用链
2. 可复用组件/接口
3. 最小技术计划
4. 测试计划
5. 风险点

你确认后，第三条消息：

text 复制代码

进入执行：
按确认后的技术计划实现。
遇到不确定的代码设计问题先问 JiaSen。
改完按验收矩阵逐项验证。

9. 多线程团队模式的落地方式

当任务很大时，可以把不同工作拆到子线程：

text 复制代码

主线程：总控、汇总、最终执行
子线程 A：只读 PRD，整理需求规格
子线程 B：只读代码，整理调用链
子线程 C：只读 Figma/截图，整理设计映射
子线程 D：review 风险和测试缺口

主线程负责合并结论，避免多线程各改各的。

适合使用多线程的条件：

材料很多。
代码范围不确定。
需要并行查前端和后端。
需要先出方案但不想等一个线程慢慢读完所有内容。

不适合多线程的情况：

小 bug。
明确单文件修改。
生产 DB 写入前的最终执行。
需要强一致上下文的 prompt 精修。

启动 Prompt：

text 复制代码

多线程团队模式：
目标：
材料位置：
请你作为主线程拆分任务：
- 子线程 A：PRD/需求规格
- 子线程 B：代码侦察
- 子线程 C：设计映射
- 子线程 D：测试风险 review
所有子线程只读，不改代码。
主线程最后汇总成规格书、技术计划、验收矩阵。

10. 最推荐你马上采用的 3 个习惯

10.1 每个中型任务先生成 `01_spec.md`

不要先问"怎么改代码"，先把需求变成规格书。你确认规格书后，后面的 Plan 才会更稳。

10.2 每次开发前生成 `05_acceptance_matrix.md`

验收矩阵会减少大量"改完再解释"的时间。

10.3 大任务建立材料包目录

材料包让任务可以暂停、恢复、复盘、拆线程。

推荐最小目录：

text 复制代码

00_raw/
01_spec.md
04_tech_plan.md
05_acceptance_matrix.md
06_execution_log.md

11. 你可以直接复制的高频 Prompt

11.1 PRD 整理

text 复制代码

PRD 整理模式：
下面是 PRD/飞书内容。
先不要写代码。
请整理为：
1. 需求规格书
2. 非目标
3. 业务规则
4. 边界场景
5. 数据来源
6. 待确认问题
7. 初版验收矩阵
如果信息不足，只列待确认问题，不要自行脑补。

11.2 PRD + Figma

text 复制代码

PRD + Figma 模式：
下面是 PRD 和设计稿截图/链接/说明。
先不要写代码。
请输出：
1. 需求规格书
2. 页面结构
3. 组件清单
4. 每个组件的状态
5. 数据字段映射
6. 交互清单
7. 验收矩阵
8. 待确认问题

11.3 规格确认后进入 Plan

text 复制代码

进入计划模式：
基于已确认的需求规格书和验收矩阵，读取代码。
先不要改代码。
请输出：
1. 代码入口
2. 调用链
3. 修改文件清单
4. 测试计划
5. 风险点
6. 需要 JiaSen 确认的问题

11.4 计划确认后执行

text 复制代码

进入执行：
按已确认计划实现。
不要扩大范围。
遇到不确定的代码设计问题先问 JiaSen。
改完按验收矩阵逐项验证，并输出验证结果。

11.5 只读生产排查

text 复制代码

生产证据模式：
现象：
范围：
只读排查，不要写库。
请输出：
1. 代码路径
2. 表/模型/字段
3. 原始记录/日志/JSON
4. 根因
5. 修复 SQL 或脚本草案
6. 执行风险

11.6 真实团队模式

text 复制代码

真实团队模式：
目标：
材料：
请拆成多个只读角色并行分析：
1. PRD 规格
2. 代码路径
3. 设计映射
4. 测试和风险
最后由主线程汇总为：
- 需求规格书
- 技术计划
- 验收矩阵
- 待确认问题
没有确认前不要改代码。

11.7 材料包生成

text 复制代码

材料包模式：
请在 Downloads 下为这个任务建立材料包目录。
目录包含：
00_raw/
01_spec.md
02_design_mapping.md
03_code_recon.md
04_tech_plan.md
05_acceptance_matrix.md
06_execution_log.md
先根据我提供的材料生成 01_spec.md 和 05_acceptance_matrix.md。

12. 最终建议

你的下一次效率跃迁，优先级应该是：

规格书优先，而不是直接进入代码。
PRD/飞书/Figma 全部进入材料包。
Plan 模式只在规格确认后使用。
每个任务都绑定验收矩阵。
大任务用真实多线程团队模式拆只读分析。

一句话版本：

text 复制代码

先把材料变成规格书，再把规格变成计划，再把计划变成验收矩阵，最后才写代码。

这比单纯"路由更快"更能提升一大截，因为它减少的是返工、误解、漏验和上下文丢失。

Codex 高效开发协作手册

1. 现有系统能力

1.1 Codex 本地工程能力

1.2 当前可用插件和 Skill

1.3 Skill、MCP、插件、模式的区别

2. 你的现有全局规则和项目规则

2.1 通用协作规则

2.3 你长期偏好的工程约束

3. 推荐协作模式

3.1 驾驶模式

3.2 侦察模式

3.3 团队模式

3.4 证据模式

3.5 审查模式

3.6 前端验证模式

3.7 文档/表格/材料模式

4. 任务应该如何选择模式

4.1 可以直接驾驶的情况

4.2 必须先侦察的情况

4.3 适合团队模式的情况

4.4 必须证据优先的情况

4.5 适合审查模式的情况

5. 关键 Prompt 模板

5.1 最快通用模板

5.2 复杂后端改动模板

5.3 新增 ry-server 异步接口模板

5.4 Prompt 或志愿助手规则调整模板

5.5 生产数据排查模板

5.6 AI 衍生数据生成/发布模板

5.7 前端页面修改模板

5.8 Review 模板

5.9 "只新增"模板

5.10 快速定位数据来源模板

6. 默认触发矩阵

7. 推荐的默认开发协议

8. 一句话启动命令

9. 最实用的结论

JiaSen 的 Codex 效率跃迁落地方案

1. 核心判断

2. 现有能力与接入边界

2.1 当前确定可用的能力

2.2 Figma 和飞书的现实接入方式

A 档：手动材料包，马上可用

B 档：文件化材料包，强烈推荐

C 档：插件/连接器直连，后续增强

3. 效率跃迁的 6 层架构

3.1 输入层：统一材料包

3.2 规格层：需求规格书

3.3 设计层：Figma/页面映射表

3.4 计划层：技术执行计划

3.5 验收层：验收矩阵

3.6 执行层：开发、测试、证据

4. 具体可执行工作流

4.1 普通小任务：目标驱动开发流

4.2 中型需求：规格书优先开发流

4.3 PRD + Figma：设计驱动开发流

4.4 复杂后端：侦察 + 计划 + 执行流

4.5 生产问题：证据优先流

4.6 多链路大任务：真实团队模式

5. 推荐的"需求材料包"标准

6. 关键产物模板

6.1 需求规格书模板

6.2 设计映射表模板

6.3 技术计划模板

6.4 验收矩阵模板

6.5 执行日志模板

7. 项目专属执行规则

7.1 ry-server 新增接口

7.2 ry-app uniapp-x

7.3 prompt / 志愿助手

7.4 AI 衍生数据

8. 一次真实需求的推荐执行顺序

9. 多线程团队模式的落地方式

10. 最推荐你马上采用的 3 个习惯

10.1 每个中型任务先生成 01_spec.md

10.2 每次开发前生成 05_acceptance_matrix.md

10.3 大任务建立材料包目录

11. 你可以直接复制的高频 Prompt

11.1 PRD 整理

11.2 PRD + Figma

10.1 每个中型任务先生成 `01_spec.md`

10.2 每次开发前生成 `05_acceptance_matrix.md`