很多人开始使用 ChatGPT、Plus、Pro、Codex 写代码以后,会经历一个很明显的阶段。
最开始:
text
打开 ChatGPT
↓
描述需求
↓
复制代码
↓
粘贴到项目
再往后:
text
把整个项目交给 Codex
↓
让 Agent 自己找文件
↓
修改代码
↓
运行测试
到这里效率已经提高很多。
但继续使用一段时间以后,又会发现一个新的问题:
每一个项目,都要重新告诉 AI 一遍规则。
比如:
text
不要乱加依赖
text
修改以后记得跑测试
text
不要使用 any
text
数据库必须走 Prisma
text
不要改公共 API
text
不要为了让测试通过就修改测试
text
先分析再修改
如果每次都要重新输入这些内容,实际上说明:
我们缺的不是一个更长的 Prompt,而是一套固定的 AI 开发环境。
所以这一篇我不继续讨论"怎么写 Prompt"。
而是直接做一件更实用的事情:
从 0 搭建一套可以长期复用的 ChatGPT + Codex AI 编程项目模板
最终我们希望得到类似这样的结构:
text
my-project/
├── AGENTS.md
├── README.md
│
├── docs/
│ ├── architecture.md
│ ├── business-rules.md
│ ├── database.md
│ └── api.md
│
├── src/
│
├── tests/
│
├── scripts/
│
├── .env.example
├── .gitignore
├── package.json
└── ...
同时建立完整流程:
text
Requirement
↓
Explore
↓
Plan
↓
Implement
↓
Test
↓
Review
↓
Commit
这套方式不仅适合 Codex。
未来即使换其他 Coding Agent,很多思想一样适用。
一、先明确目标:我们不是在搭"AI 自动写代码系统"
这个区别非常重要。
我们的目标不是:
text
给 AI 最大权限
↓
让它随便改
↓
自动提交
↓
自动上线
而是:
text
让 AI 在明确的工程边界内工作
简单来说:
text
Human
=
定义目标
判断风险
确认结果
而:
text
AI Agent
=
搜索
分析
实现
测试
Review
所以整个模板要解决 5 个问题:
text
1. AI 知道项目是什么
2. AI 知道应该怎么开发
3. AI 知道哪些事情不能做
4. AI 知道修改后怎么验证
5. 人能够快速检查 AI 做了什么
二、第一步:项目根目录建立 AGENTS.md
如果整个项目只让我增加一个专门给 Coding Agent 的文件,我会优先建立:
text
AGENTS.md
它的作用可以理解成:
AI 开发规范
很多以前需要重复写进 Prompt 的规则,都可以放到这里。
三、一个基础 AGENTS.md 模板
可以先从下面这个版本开始。
markdown
# AGENTS.md
## Project Overview
This is a production application.
Main goals:
- Keep behavior stable.
- Prefer maintainable code.
- Minimize unnecessary changes.
- Preserve backwards compatibility.
## Before Coding
Before modifying code:
1. Inspect the existing implementation.
2. Search for reusable utilities.
3. Understand the current data flow.
4. Identify affected tests.
5. Identify compatibility risks.
For tasks involving multiple modules,
provide an implementation plan before coding.
## Change Scope
Prefer the smallest reasonable change.
Do not:
- refactor unrelated modules;
- rename unrelated files;
- reformat large unrelated code sections;
- change public APIs without explicit requirement;
- add new dependencies without a clear reason.
## Code Style
Follow the existing project style.
Prefer:
- small functions;
- explicit naming;
- shared types;
- reusable utilities;
- clear error handling.
Avoid duplicated business logic.
## TypeScript
If this is a TypeScript project:
- avoid `any`;
- avoid `@ts-ignore`;
- avoid `@ts-nocheck`;
- fix the underlying type issue;
- reuse existing shared types where possible.
## Dependencies
Before adding a dependency:
1. check existing dependencies;
2. check native platform capabilities;
3. explain why a new dependency is necessary.
Do not install packages for trivial functionality.
## Database
Use the existing database abstraction.
Do not create a second database client.
Schema changes must include migration files.
Do not modify production data directly.
For critical writes, consider:
- transaction boundaries;
- idempotency;
- concurrency;
- rollback behavior.
## API
Preserve existing API behavior unless explicitly required.
Do not silently change:
- response formats;
- status codes;
- parameter names;
- authentication behavior.
Breaking changes must be reported before implementation.
## Testing
After modifying business logic:
run relevant tests.
After changing typed code:
run type checking.
After frontend changes:
run lint where appropriate.
Do not modify existing tests only to make them pass.
If a test expectation must change,
explain why the expected behavior changed.
## Security
Never expose or commit:
- passwords;
- private keys;
- API keys;
- access tokens;
- refresh tokens;
- database credentials.
Use placeholders when discussing secrets.
## Review
Before declaring a task complete:
1. inspect the Git diff;
2. look for unrelated changes;
3. look for compatibility risks;
4. look for missing tests;
5. look for security issues.
## Final Report
After completing a task, report:
1. Files Changed
2. Behavior Changed
3. Tests Executed
4. Test Results
5. Remaining Risks
这个版本先解决:
text
开发纪律
而不是具体业务。
四、AGENTS.md 不应该只写"代码风格"
很多人第一次写类似规则文件,会全部写:
text
缩进两个空格
变量使用 camelCase
函数不超过 50 行
这些当然可以写。
但对 Coding Agent 来说,更重要的往往是:
text
业务边界
例如:
text
不要修改支付状态定义
或者:
text
用户 Owner 不允许直接删除
或者:
text
订单完成以后禁止回退到 Paid
这些信息比:
text
单引号还是双引号
重要得多。
五、第二步:建立 docs/architecture.md
AGENTS.md 主要回答:
text
怎么开发?
但 AI 还需要知道:
text
系统为什么这样设计?
这时可以建立:
text
docs/architecture.md
例如:
markdown
# Architecture
## Overview
The system consists of:
- Web Application
- API Server
- PostgreSQL
- Redis
- Background Worker
## Request Flow
Browser
→ Next.js API
→ Service Layer
→ Repository
→ PostgreSQL
## Authentication
Authentication is session-based.
Session data is stored in Redis.
The browser stores only the session ID.
## Background Jobs
Long-running tasks are sent to the worker queue.
Examples:
- email delivery;
- report generation;
- image processing.
## Important Boundaries
API routes should not contain complex business logic.
Business logic belongs in services.
Database access belongs in repositories.
Shared validation logic belongs in shared utilities.
这种文档最大的价值是:
当 AI 准备写:
text
Controller 里面直接查询数据库
的时候,它可以看到项目原本的架构原则:
text
Route
↓
Service
↓
Repository
六、第三步:建立 business-rules.md
这个文件我认为很多项目都严重缺失。
因为程序真正最容易出 Bug 的东西,并不是语法。
而是:
text
业务规则
例如:
text
一个 Workspace 至少必须有一个 Owner。
text
已经退款的订单不能再次退款。
text
优惠券不能和会员折扣同时使用。
text
邀请链接只能使用一次。
这些东西通常散落在:
text
if
else
数据库
接口
历史代码
里面。
可以统一整理:
text
docs/business-rules.md
七、business-rules.md 示例
markdown
# Business Rules
## Workspace
A workspace must always have at least one owner.
The current owner cannot leave the workspace
until ownership is transferred.
## Invitation
An invitation:
- expires after 24 hours;
- can only be used once;
- cannot be accepted by another email address.
Existing workspace members cannot accept invitations again.
## Orders
An order can move through:
Created
→ Paid
→ Processing
→ Completed
Cancelled orders cannot return to Paid.
Completed orders cannot be edited.
## Payment
Payment callbacks may be delivered multiple times.
All payment processing must be idempotent.
## Credits
Credits must never become negative.
Credit changes must have an audit record.
以后 Codex 修改相关模块时,就拥有了:
text
代码上下文
+
业务上下文
这两个结合起来,稳定性会高很多。
八、第四步:建立 database.md
数据库是 Coding Agent 特别容易造成大问题的地方。
因为:
text
改前端组件
出错可能只是页面挂了。
但:
text
数据库 Schema
改错可能造成:
text
数据丢失
所以数据库最好单独建文档。
例如:
markdown
# Database Rules
Database: PostgreSQL
ORM: Prisma
## Rules
All schema changes require migrations.
Never directly rename a production column
without considering backwards compatibility.
Prefer additive migrations.
## High-Risk Tables
users
orders
payments
credits
Changes to these tables require:
- compatibility analysis;
- migration plan;
- rollback plan.
## Transactions
The following operations must be atomic:
- credit deduction;
- refund processing;
- order settlement.
## Idempotency
Payment webhook processing must be idempotent.
Use the payment provider event ID
as the idempotency key.
九、第五步:建立 api.md
接口也是 AI 特别容易"顺便优化"的地方。
例如原本:
json
{
"data": {}
}
AI 觉得这样不够现代,改成:
json
{
"success": true,
"result": {}
}
代码可能更"漂亮"。
客户端却全挂了。
所以:
text
API Compatibility
一定要明确。
十、api.md 可以记录什么?
例如:
markdown
# API Rules
## Response Format
Success:
```json
{
"data": {}
}
Error:
json
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable message"
}
}
Do not introduce a new response format.
Compatibility
Existing public API behavior should remain compatible.
Do not change:
- endpoint paths;
- parameter names;
- response field names;
- authentication requirements;
unless explicitly requested.
Pagination
Use:
page
pageSize
total
Do not introduce cursor pagination
into existing endpoints without a migration plan.
---
# 十一、第六步:建立 .env.example,而不是让 AI 直接看 .env
真实 `.env` 可能包含:
```text
API_KEY
DATABASE_PASSWORD
JWT_SECRET
AWS_SECRET
STRIPE_SECRET
没有必要全部放给 Agent。
更推荐:
text
.env.example
例如:
env
DATABASE_URL=<DATABASE_URL>
REDIS_URL=<REDIS_URL>
AUTH_SECRET=<AUTH_SECRET>
EMAIL_API_KEY=<EMAIL_API_KEY>
重点是告诉 AI:
text
系统需要哪些环境变量
而不是:
text
真实 Secret 是什么
十二、第七步:把测试命令标准化
AI 写完以后最大的风险之一就是:
text
"代码看起来没问题"
但没有实际验证。
所以最好让项目拥有明确命令:
json
{
"scripts": {
"dev": "next dev",
"test": "vitest run",
"test:watch": "vitest",
"typecheck": "tsc --noEmit",
"lint": "eslint .",
"build": "next build"
}
}
这样 Agent 不需要猜:
text
这个项目怎么跑测试?
它只需要执行:
bash
pnpm test
pnpm typecheck
pnpm lint
即可。
十三、为什么"统一命令"很重要?
假设你的项目测试方式是:
bash
NODE_ENV=test pnpm vitest src/server
但:
text
README 没写
package.json 也没写
开发者自己知道。
AI 不知道。
结果可能:
text
npm test
然后:
text
Command not found
最后 AI 告诉你:
无法执行测试。
所以一个 Agent Friendly Project 最重要的特征之一就是:
常用操作可以通过固定命令完成。
十四、第八步:Git 工作流也要规范
我比较建议 AI 修改项目时保持:
text
一个任务
=
一个相对独立的 Diff
不要:
text
Feature
+
Refactor
+
Formatting
+
Dependency Update
全部混在一个任务里。
否则最后:
text
git diff
很难 Review。
十五、推荐的 Git 修改原则
可以写入 AGENTS.md:
markdown
## Git Change Rules
Keep changes focused on the current task.
Do not:
- reformat unrelated files;
- rename unrelated files;
- update unrelated dependencies;
- fix unrelated warnings.
If unrelated issues are discovered,
report them separately.
The final diff should be easy to review.
核心目标就是:
text
Reviewable Diff
十六、AI 编程时代,Diff 大小本身就是一个风险指标
例如需求:
text
修复登录按钮重复提交
结果:
text
42 files changed
+3200
-2700
这种情况即使测试通过,也应该先问:
text
为什么改这么多?
可以提前给 Codex:
text
If the task unexpectedly requires a large diff,
stop and explain why.
这句话很实用。
十七、第九步:建立固定 Explore Prompt
项目搭好以后,就可以把工作流模板固定下来。
第一阶段:
Explore
text
Task:
[描述当前需求]
Do not modify files yet.
First inspect the existing implementation.
Identify:
1. relevant entry points;
2. related modules;
3. data flow;
4. database writes;
5. external side effects;
6. existing tests;
7. compatibility risks.
Then report:
Current Behavior
Relevant Files
Potential Root Cause / Implementation Area
Risks
Recommended Scope
Do not implement yet.
十八、为什么一定要有 Explore?
因为 Coding Agent 最容易出现:
text
根据文件名猜实现
例如需求:
text
修改登录
它看到:
text
login.ts
就开始改。
但真正认证逻辑可能在:
text
auth-service.ts
session.ts
middleware.ts
redis.ts
所以:
text
Search before Edit
是非常重要的一条原则。
十九、第十步:固定 Plan Prompt
Explore 完以后:
text
Create an implementation plan.
For every step include:
- Goal
- Files
- Reason
- Risk
- Verification
Constraints:
- smallest reasonable change;
- preserve backwards compatibility;
- reuse existing abstractions;
- avoid unnecessary dependencies;
- do not refactor unrelated code.
Do not implement yet.
如果 Plan 看起来没问题,再进入 Implement。
二十、第十一步:Implement Prompt
text
Implement the approved plan.
Rules:
1. Stay within the approved scope.
2. Reuse existing project patterns.
3. Do not refactor unrelated code.
4. Do not add dependencies unless necessary.
5. Preserve existing public behavior.
6. Add tests for new or changed behavior.
After implementation:
run relevant tests.
注意:
text
Stay within the approved scope.
非常重要。
否则 Agent 在开发过程中可能发现其他问题:
text
这里顺便也可以优化
然后越改越多。
二十一、第十二步:Verify Prompt
代码完成以后,不要直接:
text
Done
应该进入:
text
Verification
例如:
text
Verify the implementation.
Run the relevant:
- unit tests;
- integration tests;
- type checking;
- lint;
- build;
based on the files changed.
Do not claim success based only on code inspection.
Report:
Command
Result
Failure reason if any
最后一句很重要:
text
Do not claim success based only on code inspection.
二十二、测试失败以后,不允许 Agent 第一反应修改测试
一个非常危险的流程:
text
代码修改
↓
测试失败
↓
AI 修改测试
↓
测试通过
看起来:
text
PASS
实际上可能是:
text
把原本正确的测试改错了
所以规则写清楚:
text
If an existing test fails:
first determine whether the implementation
violated existing behavior.
Do not modify existing expectations
unless the product behavior intentionally changed.
二十三、第十三步:Self Review Prompt
代码和测试都完成以后,再让 Codex:
text
Review the final Git Diff.
Do not modify files.
Look specifically for:
- logic bugs;
- accidental behavior changes;
- unrelated changes;
- missing tests;
- security issues;
- race conditions;
- API compatibility issues;
- data integrity risks.
Rank findings:
Critical
High
Medium
Low
If there are no meaningful findings,
say so clearly.
Do not invent issues just to produce output.
这一步相当于:
text
Developer Mode
切换到:
text
Reviewer Mode
二十四、第十四步:人工 Review
这一阶段千万不要省。
至少自己看:
bash
git status
然后:
bash
git diff
重点检查:
text
改了几个文件?
text
有没有新依赖?
text
有没有改 Schema?
text
有没有修改公共 API?
text
有没有碰测试?
text
有没有出现 Secret?
text
有没有无关重构?
二十五、推荐建立一个"AI Task Checklist"
你甚至可以在项目里建立:
text
docs/ai-task-checklist.md
内容:
markdown
# AI Task Checklist
## Before Coding
- [ ] Requirement is clear
- [ ] Existing implementation inspected
- [ ] Relevant files identified
- [ ] Compatibility risk identified
- [ ] Tests identified
## Implementation
- [ ] Scope remains focused
- [ ] No unnecessary dependency added
- [ ] Existing project patterns reused
- [ ] No unrelated refactor
## Verification
- [ ] Unit tests executed
- [ ] Type check executed
- [ ] Lint executed if applicable
- [ ] Build executed if applicable
## Review
- [ ] Git diff reviewed
- [ ] No secrets added
- [ ] No accidental API changes
- [ ] No unplanned schema changes
- [ ] New behavior has tests
这套东西看起来很传统。
实际上:
Agent 越强,Checklist 越重要。
二十六、为什么?
因为 AI 最大特点是:
text
执行速度很快
以前一个开发者:
text
改 20 个文件
可能需要:
text
几个小时
你有很多时间意识到:
text
这个改动是不是太大?
现在 Agent:
text
几分钟
就可能改完。
于是:
text
速度 ↑
意味着:
text
需要控制 ↑
二十七、一个完整项目目录可以长这样
最终可以整理成:
text
my-project/
├── AGENTS.md
│
├── README.md
│
├── docs/
│ ├── architecture.md
│ ├── business-rules.md
│ ├── database.md
│ ├── api.md
│ └── ai-task-checklist.md
│
├── src/
│ ├── app/
│ ├── services/
│ ├── repositories/
│ ├── lib/
│ └── types/
│
├── tests/
│ ├── unit/
│ └── integration/
│
├── scripts/
│
├── .env.example
├── .gitignore
├── package.json
└── tsconfig.json
这个结构没有什么"神奇技术"。
核心只是:
text
把原本存在开发者脑子里的信息
逐渐变成:
text
Agent 可以读取的项目上下文
二十八、再进一步:把业务知识也版本化
以前业务知识通常存在:
text
产品经理脑子里
或者:
text
老员工脑子里
问题是:
text
人离职
↓
知识消失
如果以后项目越来越依赖 AI Agent,我认为非常值得把:
text
Business Rules
Architecture Decisions
Compatibility Rules
放进 Git。
这样:
text
代码
+
业务知识
+
工程规范
一起版本化。
二十九、Architecture Decision Record 也非常适合 AI
例如:
text
为什么不用 MongoDB?
text
为什么 Session 存 Redis?
text
为什么订单不用 Event Sourcing?
如果没有记录,AI 可能某一天:
"当前架构可以优化,我建议......"
然后又把历史讨论重新做一次。
可以增加:
text
docs/decisions/
例如:
text
001-use-postgresql.md
002-use-redis-session.md
003-no-microservices-yet.md
三十、ADR 示例
markdown
# ADR-003: Keep the Application as a Modular Monolith
## Decision
Do not split the current application
into microservices.
## Reason
Current team size is small.
Operational complexity would outweigh the benefits.
## Reconsider When
Reconsider if:
- deployment frequency becomes a bottleneck;
- independent scaling becomes necessary;
- team ownership boundaries become clear.
以后 Agent 再看到:
text
这个模块有点大
就不会第一反应:
text
拆微服务
因为项目已经记录:
text
为什么暂时不拆
三十一、ChatGPT 在这套模板里扮演什么角色?
ChatGPT 更适合放在:
text
需求之前
和:
text
重大决策之前
例如:
text
帮我分析这个需求有哪些隐藏边界条件。
或者:
text
帮我比较这三种数据库方案。
或者:
text
帮我把这个产品需求拆成 5 个可以独立开发的 Task。
然后把清晰 Task 交给 Codex。
三十二、Codex 扮演什么角色?
Codex 更适合:
text
进入真实项目
执行:
text
Search
↓
Read
↓
Plan
↓
Edit
↓
Run
↓
Review
所以一个比较舒服的组合方式是:
text
ChatGPT
=
需求 / 思考 / 决策
text
Codex
=
工程执行
不是绝对划分。
但是作为工作流,非常好理解。
三十三、Plus / Pro 用户真正需要优化的是"重复使用率"
如果只是偶尔:
text
问一个代码问题
不需要搭这么多东西。
但如果已经每天大量使用 ChatGPT、Codex,
那么:
text
每次重复告诉 AI 同样的规则
本身就是浪费。
把这些规则沉淀成:
text
AGENTS.md
docs
scripts
tests
等于:
把 Prompt 变成基础设施。
这是我认为 AI 编程从:
text
"会用"
进入:
text
"工程化使用"
的一个明显标志。
三十四、这套模板最大的价值不是让 AI 写得更多
恰恰相反。
它很多规则都在告诉 AI:
text
不要乱改
text
不要扩范围
text
不要加依赖
text
不要破坏兼容
text
不要没跑测试就说完成
为什么?
因为真正的软件工程价值不是:
text
一天生成多少行代码
而是:
text
正确地完成多少任务
三十五、一套最终版万能 Task 模板
如果你只想保存一条,可以保存下面这个。
text
Task:
[描述任务]
Goal:
[描述最终目标]
Before Coding:
1. Read AGENTS.md.
2. Inspect the existing implementation.
3. Identify the minimum relevant files.
4. Identify existing tests.
5. Identify compatibility risks.
Do not modify files until the implementation path is clear.
Constraints:
- Prefer the smallest reasonable change.
- Do not refactor unrelated code.
- Do not introduce new dependencies unnecessarily.
- Preserve existing APIs and behavior unless explicitly required.
- Reuse existing abstractions.
- Do not hide type problems with `any` or ignore directives.
- Do not modify tests merely to make them pass.
Implementation:
Follow the approved implementation plan.
Add or update tests for changed behavior.
Verification:
Run relevant:
- tests;
- type checking;
- lint;
- build.
Report exact commands and results.
Review:
Inspect the final Git Diff for:
- accidental changes;
- security risks;
- compatibility issues;
- data integrity issues;
- concurrency issues;
- missing tests.
Final Report:
1. Current / Root Cause
2. Files Changed
3. Behavior Changed
4. Tests Added
5. Commands Executed
6. Test Results
7. Remaining Risks
很多日常需求,只需要替换:
text
Task
和:
text
Goal
即可。
三十六、完整 AI 编程工作流
最后再把整套流程串起来:
text
Product Requirement
↓
ChatGPT
↓
Requirement Clarification
↓
Task Definition
↓
Codex
↓
Read AGENTS.md
↓
Explore Repository
↓
Implementation Plan
↓
Human Approval
↓
Implementation
↓
Unit Test
↓
Type Check
↓
Lint / Build
↓
Agent Self Review
↓
Human Git Diff Review
↓
Commit
↓
Merge
如果是高风险任务:
text
Payment
Database
Authentication
Permission
还可以额外增加:
text
Security Review
和:
text
Data Integrity Review
三十七、结语:AI 编程下一阶段,拼的是"环境设计"
早期使用 ChatGPT 编程,我们研究的是:
text
怎么问
后来开始研究:
text
怎么写 Prompt
再往后:
text
怎么让 Agent 操作项目
而我认为真正进入工程化以后,下一步会越来越重要的是:
怎么给 Agent 设计一个正确的工作环境。
这里包括:
text
AGENTS.md
告诉它:
text
怎么工作
text
architecture.md
告诉它:
text
系统怎么组成
text
business-rules.md
告诉它:
text
业务不能违反什么
text
database.md
告诉它:
text
数据怎么保证安全
text
tests
告诉它:
text
怎么证明改动没问题
text
Git Diff
告诉人:
text
AI 实际做了什么
最终组合成:
text
Context
+
Rules
+
Tools
+
Verification
+
Human Judgment
这才是一套真正稳定的 AI Coding Workflow。
所以如果你已经在使用 ChatGPT Plus、Pro、Codex 编程,不妨不要再只收藏:
text
100 个 Prompt
可以开始尝试建立自己的:
AI Project Template
当这些规则和文档沉淀下来以后,你会发现:
同一个项目里,后面的每一个 AI 编程任务都会越来越顺。
因为你不需要再从:
text
"你好,这是一个 Next.js 项目......"
开始。
AI 一进入仓库,就已经知道:
text
这是什么系统
text
哪些规则不能破坏
text
代码应该怎么改
text
改完应该跑什么
text
最后应该怎么汇报
而这,可能才是 ChatGPT、Plus、Pro、Codex 从"聊天工具"真正进入软件工程基础设施的重要一步。