Frontend
前端界面层
用户看到和操作的部分
页面用户打开的 URL 和视图
组件按钮、表单、卡片、表格
状态加载、空数据、错误、选中
请求调用后端接口拿数据
验证浏览器打开页面检查
请先定位这个按钮属于哪个页面和组件，再说明点击后触发什么状态和接口。不要先改代码。
Development Map
先懂软件由哪些层组成
前端层
用户看到和点击的部分。
- 页面
- 组件
- 路由
- 状态
后端层
业务规则和接口。
- API
- 权限
- 任务
- 日志
数据层
业务事实和历史记录。
- 数据库
- 缓存
- 文件
- 迁移
开发复杂度来自依赖关系
需求你到底要改变什么行为
入口页面、接口、命令或任务在哪里
数据流数据从哪来，到哪里去
影响面哪些旧功能必须保留
验证怎么证明真的完成
Architecture Cards
开发架构卡：一张卡理解一个层次
学习 Codex 开发，不能只记“前端后端数据库”这几个词。你要知道每一层是什么、Codex 怎么读、怎么改、怎么验证。
Backend
后端业务层
处理规则、权限和接口的部分
路由请求进来走哪个接口
权限谁能访问和修改
业务真正的规则和计算
错误异常、日志、返回码
验证curl、测试、日志
请说明这个接口的输入、输出、权限检查、业务逻辑和错误处理，再给修改计划。
Database
数据库层
业务事实和历史记录的存放处
表数据放在哪个表
字段每列代表什么
关系用户、项目、订单如何关联
迁移结构变化怎么上线
验证只读查询和测试数据
请先只读数据库相关代码和迁移文件，说明数据表关系。不要直接修改生产数据。
Iteration
迭代交付
Codex 最适合小步迭代，而不是一次重写
目标先做最小可用版本
计划拆成 2 到 4 步
实现每步只改相关文件
验证每步都有证据
反馈根据结果继续改
请把这个需求拆成三步迭代：每步说明改什么、怎么验证、保留哪些旧功能。
Developer Concepts
Codex 做代码类工作前，你要先懂这些软件概念
不要求每个人都会写程序，但要知道 Codex 在项目里到底读什么、改什么、验证什么。
软件开发
软件是行为，不只是页面
一个需求会影响页面、接口、数据、权限、日志、测试和部署。让 Codex 先说清行为变化。
前后端
用户看到的是前端，规则通常在后端
按钮、表单、列表在前端；权限、计算、保存、任务调度多在后端。
编程语言
语言决定运行环境和验证方式
JavaScript/TypeScript 常见于网页；Python 常见于脚本和 AI；Java/Rust/Go 常见于后端服务。
数据库
数据结构比页面更难随便改
字段、表关系、迁移和历史数据会影响线上稳定性。数据库相关任务要先只读分析。
文档
README 和 AGENTS.md 是工程入口
好的文档能告诉 Codex 项目怎么启动、怎么测试、什么不能改。
软件复杂度
复杂度来自依赖和历史
小页面、内部工具、业务系统、数据平台不是一个难度。越复杂越需要规划模式。
迭代
先做小闭环，再继续扩展
Codex 最适合一次完成一个可验证的小目标，而不是一次性重写整个系统。
大模型利用
人负责目标和验收，模型负责执行和整理
不要把最终判断交给模型。让它读、改、跑、总结，但你要定义边界。
生产风险
能跑不代表能上线
上线前要检查配置、权限、数据迁移、回滚方式和真实用户路径。
Standard Method
Codex 标准使用方法
这不是小技巧，是固定流程。复杂开发任务必须先规划，再执行，再验证。
上下文
给项目和目标
告诉 Codex 项目位置、业务目标、不能改的边界和必须保留的旧功能。
请先阅读 README、AGENTS.md 和相关页面。目标是……不要改……必须保留……
规划
只读分析，不先改
让 Codex 找文件、解释结构、画影响范围、提出修改方案。
请进入规划模式：只读文件，列出现状、方案、影响范围和验证方式，先不要修改。
执行
小步实现
确认计划后再改。每一步只改目标相关内容，不顺手重构。
按计划执行。只改相关文件，每完成一步说明改了什么和为什么。
验证
用证据收尾
跑测试、构建、访问页面、检查接口或日志，并说明未覆盖风险。
请运行相关验证，列出命令、结果、访问 URL、未覆盖风险。
AGENTS.md
AGENTS.md 是给 Codex 的项目操作手册
模块
要写什么
为什么重要
示例
项目地图
前端、后端、数据库、脚本、文档目录
避免改错层
`frontend/` 是页面，`backend/` 是接口
运行方式
启动、测试、构建、常用 URL
让 Codex 能验证
`npm run dev`，`npm test`
边界规则
不能改什么，哪些行为必须保留
控制风险
不要删除旧页面，不要动密钥
交付标准
改动说明、验证命令、风险
让结果可复核
最后列出验证了哪些 URL