很多人第一次在 ChatGPT Plus、Pro 或 Codex CLI 中使用 Codex，通常会直接打开一个项目，然后输入：

帮我看看这个项目。

或者：

帮我继续开发这个功能。

小项目可能还能工作。

但项目一旦超过几万行代码，很快就会遇到几个问题：

• Codex 不知道项目架构；
• 不知道哪些目录允许修改；
• 不知道应该运行哪些测试；
• 不知道项目的代码规范；
• 不知道哪些历史设计不能碰；
• 修改完成后没有统一验证标准；
• 一个任务修好了，却破坏了另外一个模块。

很多时候并不是 Codex 模型能力不够。

真正的问题是：

你的代码仓库并没有为 Coding Agent 提供足够清晰的工作环境。

OpenAI 官方也明确建议通过 AGENTS.md 给 Codex 提供仓库级持续上下文，包括代码组织方式、测试命令和项目规范；官方内部使用经验也强调，把 Prompt 写得像 GitHub Issue，并提供明确文件、组件和已有实现参考，往往能得到更好的结果。

所以这篇不再讨论 Codex 是什么。

直接做一件事情：

从零把一个普通代码仓库改造成适合 Codex 工作的 Agent-Friendly Repository。

---

一、先看最终项目结构

假设我们有一个典型 Web 项目：

shop-system/
│
├── AGENTS.md
├── README.md
├── ARCHITECTURE.md
│
├── docs/
│   ├── index.md
│   ├── business-rules.md
│   ├── database.md
│   ├── api.md
│   └── decisions/
│
├── frontend/
│   ├── AGENTS.md
│   └── src/
│
├── backend/
│   ├── AGENTS.md
│   ├── src/
│   └── tests/
│
├── scripts/
│
├── package.json
│
└── .github/
    └── pull_request_template.md

这里每一部分都有自己的作用。

可以简单理解成：

README.md
给人看

ARCHITECTURE.md
解释系统设计

docs/
存放详细知识

AGENTS.md
告诉 Codex 怎么工作

tests/
告诉 Codex 什么叫正确

scripts/
告诉 Codex 怎么验证

Git
告诉 Codex 改了什么

这几个东西组合起来以后，AI 编程体验会比单纯扔一个仓库给 Codex 稳定很多。

---

二、第一步：创建根目录 AGENTS.md

先从最重要的文件开始。

在项目根目录创建：

AGENTS.md

不要一开始写几千行。

推荐先控制在几十到一百多行。

例如：

# Project Overview

This repository contains an e-commerce platform.

Main stack:

- Frontend: Next.js + TypeScript
- Backend: FastAPI + Python
- Database: PostgreSQL
- Cache: Redis

# Repository Structure

frontend/
Frontend application.

backend/
Backend API and business logic.

docs/
Architecture and business documentation.

scripts/
Development and verification scripts.

# General Rules

1. Do not modify unrelated files.
2. Do not introduce new dependencies unless necessary.
3. Never commit secrets or environment variables.
4. Preserve backward compatibility unless explicitly requested.
5. Prefer the smallest correct change.
6. Follow existing patterns before introducing new abstractions.

# Before Coding

Before implementing a feature:

1. Locate the relevant module.
2. Read nearby tests.
3. Look for an existing similar implementation.
4. Understand the current call chain.
5. Check docs/ for related business rules.

# Validation

Before finishing:

- Run relevant unit tests.
- Run relevant integration tests.
- Run lint.
- Run type checking.
- Review the final git diff.

# Final Response

Always summarize:

1. What changed.
2. Which files changed.
3. Tests executed.
4. Test results.
5. Remaining risks.

这一份文件已经能够解决很多问题。

Codex 第一次进入仓库，就知道：

项目是什么

主要目录是什么

哪些行为禁止

修改前应该调查什么

完成以后应该验证什么

---

三、AGENTS.md 最重要的不是“介绍项目”

这一点经常被误解。

很多人把 AGENTS.md 写成：

我们公司成立于……

这个项目最早创建于……

项目的愿景是……

这些内容不是完全没用。

但对于 Coding Agent 来说，Signal 很低。

真正高价值的信息是：

Where

How

Constraint

Validation

Definition of Done

也就是：

代码在哪里？

应该怎么改？

什么不能做？

怎么判断正确？

什么情况下才算完成？

---

四、建议使用这六个模块设计 AGENTS.md

一个比较实用的结构：

Project
Architecture
Commands
Rules
Workflow
Definition of Done

完整示例：

# Project

This is an order management system.

# Architecture

HTTP requests:

Router
→ Controller
→ Service
→ Repository
→ Database

Rules:

- Controller handles HTTP concerns only.
- Service owns business logic.
- Repository owns database access.

# Commands

Install:

npm install

Development:

npm run dev

Test:

npm test

Lint:

npm run lint

Type Check:

npm run typecheck

# Rules

- TypeScript strict mode must remain enabled.
- Never use `any`.
- Do not call Prisma directly from controllers.
- Do not add dependencies without justification.
- Do not silently catch exceptions.
- Do not modify generated files.

# Workflow

Before implementing:

1. Search for existing implementation.
2. Read relevant tests.
3. Identify impacted modules.
4. Make a minimal plan.

After implementing:

1. Run targeted tests.
2. Run lint.
3. Run typecheck.
4. Inspect git diff.

# Definition of Done

A task is complete only when:

- Requirement is implemented.
- Existing behavior is preserved.
- Tests are added when appropriate.
- Relevant tests pass.
- Lint passes.
- Type checking passes.

这就已经非常接近一个给 AI Agent 使用的：

Engineering Contract

---

五、不要把所有知识都塞进 AGENTS.md

这是第二个常见错误。

假设项目里存在：

订单规则

支付规则

库存规则

优惠规则

用户权限

退款规则

数据库说明

API 文档

全部塞进一个 AGENTS.md：

AGENTS.md
8000 行

理论上信息更多了。

实际效果却可能变差。

因为 Agent 每一次任务都要吃进去大量无关 Context。

OpenAI 在公开介绍内部 Agent-first 工程实践时，也提出一种非常值得参考的方法：

把 AGENTS.md 当目录，而不是百科全书。

具体知识放在结构化 docs/ 中，AGENTS.md 负责告诉 Agent 应该去哪里寻找。

例如：

# Documentation

Architecture:

docs/architecture.md

Database:

docs/database.md

Business rules:

docs/business-rules.md

Payment:

docs/payment.md

Inventory:

docs/inventory.md

这样如果任务是：

修复库存扣减问题。

Agent 才需要进一步读取：

docs/inventory.md

而不是每一次修改 CSS 都读取库存规则。

---

六、一个更合理的 docs 目录

可以设计成：

docs/
│
├── index.md
│
├── architecture/
│   ├── overview.md
│   ├── backend.md
│   └── frontend.md
│
├── business/
│   ├── order.md
│   ├── payment.md
│   ├── inventory.md
│   └── promotion.md
│
├── database/
│   ├── schema.md
│   └── transaction.md
│
├── decisions/
│   ├── 001-use-postgresql.md
│   ├── 002-no-redis-lock.md
│   └── 003-event-driven-payment.md
│
└── api/
    └── conventions.md

然后 docs/index.md：

# Documentation Index

## Architecture

- architecture/overview.md
- architecture/backend.md
- architecture/frontend.md

## Business Rules

Orders:
business/order.md

Payments:
business/payment.md

Inventory:
business/inventory.md

Promotions:
business/promotion.md

## Database

Schema:
database/schema.md

Transactions:
database/transaction.md

## Architecture Decisions

See:
decisions/

这样 Agent 可以逐层查找。

---

七、把“隐性知识”写下来，比写代码规范更重要

真正容易让 Codex 犯错的，通常不是：

使用 2 个空格还是 4 个空格。

这些 Linter 可以解决。

真正危险的是：

只有老员工知道的规则。

例如：

支付成功以后不能直接修改订单状态，必须经过 OrderStateMachine。

或者：

库存绝对不能在 Controller 层修改。

或者：

用户余额虽然存在 users.balance，但这是只读缓存，真正余额来自 Ledger。

这种信息 AI 从代码表面不一定能够准确推断。

应该明确写下来：

# Important Business Constraints

## Balance

`users.balance` is a cached value.

Never directly mutate:

users.balance

All balance changes must be created through:

LedgerService

## Order State

Never update:

orders.status

directly.

All transitions must go through:

OrderStateMachine.transition()

这样的 Context 非常值钱。

---

八、第二步：按目录拆分 AGENTS.md

大型 Monorepo 不应该只有一个 AGENTS.md。

例如：

project/
├── AGENTS.md
├── frontend/
│   └── AGENTS.md
└── backend/
    └── AGENTS.md

根目录：

# Global Rules

- Do not commit secrets.
- Do not add dependencies unnecessarily.
- Keep changes scoped to the requested task.
- Run relevant validation before finishing.

Frontend：

# Frontend Rules

Stack:

- Next.js
- React
- TypeScript

## Structure

src/app
Routes.

src/components
Reusable UI.

src/hooks
React hooks.

src/services
HTTP clients.

## Rules

- Prefer Server Components.
- Use Client Components only when state or browser APIs are required.
- Do not fetch APIs directly inside reusable UI components.
- Use the existing design system.
- Do not introduce a second state-management library.
- Avoid `any`.

## Validation

npm run lint
npm run typecheck
npm test

Backend：

# Backend Rules

Stack:

- Python
- FastAPI
- SQLAlchemy
- PostgreSQL

## Architecture

Router
→ Service
→ Repository
→ Database

## Rules

- Routers do not access database sessions directly.
- Business logic belongs in services.
- SQL belongs in repositories.
- All public functions require type annotations.
- Never swallow exceptions without logging.

## Validation

pytest
ruff check .
mypy app

Codex 当前的指令解析机制支持从项目根目录一路到当前工作目录读取相关 AGENTS.md / AGENTS.override.md，更深层目录可以提供更具体的项目指令。

这就非常适合 Monorepo。

---

九、第三步：把“怎么运行项目”标准化

Coding Agent 很依赖自动执行。

如果你们项目启动需要：

先执行 A

然后手动修改 B

再去某台服务器拿 C

最后记得开 D

那 Agent 很难可靠运行。

最好将常用操作统一成脚本。

例如：

{
  "scripts": {
    "dev": "next dev",
    "test": "vitest run",
    "test:unit": "vitest run tests/unit",
    "test:integration": "vitest run tests/integration",
    "lint": "eslint .",
    "typecheck": "tsc --noEmit",
    "verify": "npm run lint && npm run typecheck && npm test"
  }
}

于是 Codex 最后只需要：

npm run verify

而不是猜：

这个项目到底怎么测试？

---

十、建议专门创建 verify 命令

这是非常实用的一个技巧。

例如 Node：

{
  "scripts": {
    "verify": "npm run lint && npm run typecheck && npm test"
  }
}

Python 可以写：

verify:
	ruff check .
	mypy app
	pytest

然后 AGENTS.md：

# Validation

After code changes, run:

npm run verify

Do not claim completion if verification fails.

If verification cannot be executed,
explain exactly why.

这句话很重要：

Do not claim completion if verification fails.

否则 Agent 有时候会出现：

测试报错了，
但功能应该没问题。

工程项目里最好不要接受这种完成标准。

---

十一、Definition of Done 必须机器可验证

差的完成标准：

功能看起来正常。

好的完成标准：

API 返回正确。

新增测试通过。

旧测试通过。

Lint 通过。

Type Check 通过。

Git Diff 不包含无关文件。

例如：

# Definition of Done

The task is complete when:

- Expected behavior is implemented.
- Regression test exists.
- Related tests pass.
- Existing tests pass.
- Type check passes.
- Lint passes.
- No unrelated files changed.

这个标准比：

写完告诉我。

可靠得多。

---

十二、第四步：给 Codex 建立 Investigation First 习惯

对于复杂项目，不建议第一句话就是：

直接修。

建议明确规定：

# Workflow

For non-trivial tasks:

1. Investigate first.
2. Do not modify code during investigation.
3. Identify relevant files.
4. Identify current behavior.
5. Find related tests.
6. Propose a short plan.
7. Then implement.

以后就可以输入：

调查支付成功但订单仍显示“待支付”的问题。

先不要修改代码。

找出：

1. 支付回调入口；
2. PaymentService；
3. OrderService；
4. 状态转换逻辑；
5. Transaction；
6. 相关测试。

最后给出最可能的原因。

这个阶段 Agent 只做：

Search

Read

Trace

Understand

而不做：

Write

---

十三、为什么 Investigation 和 Implementation 要分开？

因为复杂 Bug 经常存在：

表面症状
≠
真实原因

例如：

页面订单状态没变化

你以为是：

Frontend Cache

实际可能是：

Payment Webhook
↓
Transaction rollback
↓
订单更新失败

如果一开始让 Agent：

修复页面状态。

它很可能去改：

React Query

Cache

Frontend State

最后越改越错。

先调查：

Data Flow

再修改：

Root Cause

成功率会高很多。

---

十四、第五步：Prompt 写成 GitHub Issue

OpenAI 内部公开的 Codex 使用经验中，一个很实用的建议就是：

Prompt 尽量像写 GitHub Issue。

也就是说，不要写：

帮我优化订单。

而应该写：

## Problem

用户取消订单后，商品库存没有恢复。

## Current Behavior

1. 用户创建订单。
2. 库存减少。
3. 用户取消订单。
4. Order status 变成 CANCELLED。
5. Inventory 没有恢复。

## Expected Behavior

取消订单成功后应该恢复已预留库存。

## Relevant Areas

可能涉及：

- OrderService
- InventoryService
- cancel order API

## Constraints

- 不修改支付退款逻辑。
- 不修改数据库 Schema。
- 保持现有 API Response。
- 使用现有 Transaction 机制。

## Validation

增加 Regression Test：

创建订单
→ 库存 -1
→ 取消订单
→ 库存恢复

然后运行：

npm run verify

这就已经是一份非常不错的 Agent Task Spec。

---

十五、最推荐的 Codex Prompt 模板

以后可以统一使用：

# Goal

描述最终目标。

# Current Behavior

描述现在发生什么。

# Expected Behavior

描述正确情况下应该发生什么。

# Scope

主要涉及哪些模块。

# Constraints

什么不能改。

# Investigation

实现前需要先调查什么。

# Validation

如何测试。

# Definition of Done

什么情况下任务才算完成。

# Final Output

最后需要汇报什么。

完整一点：

# Goal

解决用户重复提交订单的问题。

# Current Behavior

用户快速点击两次提交按钮时，
可能生成两个订单。

# Expected Behavior

同一 checkout session
只能创建一个订单。

# Constraints

- 不通过前端按钮 disabled 作为唯一保护。
- 必须有服务端保证。
- 不新增 Redis。
- 不修改现有 API response。
- 使用现有 PostgreSQL。

# Investigation

先调查：

- checkout flow
- OrderService
- transaction
- existing unique constraints
- related tests

先输出根因和实现方案，
再修改代码。

# Validation

增加并发/重复请求测试。

确保：

同一 checkout session
重复请求只产生一个 Order。

然后运行：

npm run verify

# Final Output

输出：

- 根因
- 实现方案
- 修改文件
- 测试
- 潜在风险

---

十六、第六步：要求 Agent 优先参考现有 Pattern

Agent 很容易出现一个问题：

明明项目已经有一种写法，
它又创造一种新的写法。

例如项目已有：

UserRepository

OrderRepository

PaymentRepository

你让它做 Favorites。

它突然创建：

FavoriteDAO

技术上可能没错。

但项目一致性被破坏了。

AGENTS.md 可以写：

# Consistency

Before introducing a new abstraction:

1. Search for similar existing implementations.
2. Follow the closest existing pattern.
3. Prefer consistency over introducing a theoretically cleaner abstraction.

甚至可以直接在 Prompt 中：

参考：

src/modules/cart

的结构实现 favorites。

不要创建新的架构模式。

这样结果通常更稳定。

---

十七、第七步：建立 Test-Driven Agent Workflow

对于 Bug Fix，我非常建议：

先复现
↓
写 Regression Test
↓
确认测试失败
↓
修复
↓
确认测试通过

Prompt：

修复这个 Bug。

要求：

第一步：
先增加一个能够稳定复现 Bug 的测试。

第二步：
运行测试并确认修改前测试失败。

第三步：
修复 Root Cause。

第四步：
重新运行测试并确认通过。

不要删除或弱化测试来使结果通过。

这最后一句非常重要：

不要修改测试去迁就实现。

否则有些 Agent 可能会选择：

测试失败
↓
修改 expectation
↓
测试通过

technically “green”。

实际上什么都没修。

---

十八、Bug Fix 模板

可以直接保存：

# Bug Fix Workflow

For bug fixes:

1. Reproduce the issue.
2. Identify the root cause.
3. Add a regression test that fails before the fix.
4. Implement the smallest correct fix.
5. Confirm the regression test passes.
6. Run related existing tests.
7. Review the diff for unrelated changes.

Never:

- delete a failing test without explanation;
- weaken assertions to make tests pass;
- hide an error instead of fixing its root cause.

这一段可以直接放进：

AGENTS.md

---

十九、第八步：让 Codex 自己 Review 自己的 Diff

很多人让 Agent：

实现完
↓
结束

建议再加一个阶段：

Review

Prompt：

现在先不要继续增加功能。

重新检查本次 git diff。

重点检查：

1. Logic Bug
2. Regression
3. Security Issue
4. Race Condition
5. Null Handling
6. Error Handling
7. Backward Compatibility
8. Missing Tests

如果发现明确问题，
修复后重新运行验证。

这个动作成本不高。

但经常能够找到第一次 Implementation 阶段遗漏的问题。

---

二十、最好把 Coding 和 Review 分成两个 Agent

如果任务比较重要，可以：

Agent A
负责实现

Agent B
负责 Review

第二个 Agent 不需要重新从零实现。

只告诉它：

Review 当前 Git Diff。

背景：

本次目标是修复订单重复创建。

不要改架构。

重点寻找：

- Idempotency failure
- Transaction issue
- Race condition
- Missing rollback
- Regression

工作流：

Task
↓
Developer Agent
↓
Diff
↓
Reviewer Agent
↓
Findings
↓
Developer Agent
↓
Fix
↓
Tests

对于核心业务代码，这种方式很实用。

---

二十一、第九步：让 Codex 使用 Git 作为 Context

Git 对 AI Agent 特别有价值。

因为它天然提供：

修改前

修改后

修改范围

常用命令：

git status

git diff

git diff --stat

git log --oneline -20

git blame

例如 Review 阶段：

先执行：

git diff --stat
git diff

确认没有修改与当前任务无关的文件。

甚至可以规定：

# Git Rules

Before finishing:

- inspect `git status`;
- inspect `git diff`;
- remove accidental changes;
- never modify unrelated generated files.

---

二十二、第十步：给 Agent 限制修改范围

一个很重要的工程技巧：

Scope Control

例如：

只允许修改：

backend/modules/order/
backend/tests/order/

如发现必须修改其他模块，
先说明原因。

这样可以降低：

Diff Explosion

即：

本来一个 Bug：

应该改 3 个文件

最后 Agent 改成：

37 个文件。

大型项目尤其要控制。

---

二十三、警惕“顺手重构”

Agent 特别容易说：

为了提高代码质量，
顺便进行了以下重构……

生产项目里这往往不是好事。

建议直接加：

# Change Scope

Do not perform opportunistic refactoring.

Do not:

- rename unrelated files;
- reformat entire modules;
- replace working abstractions;
- upgrade dependencies;
- reorganize folders;

unless required by the task.

原则：

Small Diff
>
Beautiful Rewrite

尤其是 Bug Fix。

---

二十四、第十一步：安全权限单独定义

2026 年 Coding Agent 已经越来越能够真正执行系统操作。

所以 Agent 工程里必须加入：

Permissions

OpenAI 2026 年公开介绍 Codex 安全运行机制时，也重点强调了技术边界、人工批准、系统访问范围和可审计性；对于高风险操作，不能只依赖 Prompt 来限制。

项目规则可以写：

# Safety

Allowed:

- read repository files;
- modify workspace files;
- run local tests;
- run lint;
- run local development tools.

Do not:

- deploy production;
- delete production data;
- access production secrets;
- rotate credentials;
- publish packages;
- merge pull requests;
- modify CI secrets;

without explicit human approval.

这就是：

Least Privilege

原则。

---

二十五、尤其不要把生产 Secret 暴露给 Coding Agent

例如：

AWS_SECRET_ACCESS_KEY

STRIPE_SECRET_KEY

DATABASE_URL=production

SSH_PRIVATE_KEY

Agent 理论上并不需要这些东西才能：

写代码

跑 Unit Test

做 Review

开发环境应该尽量：

Fake Service

Test Database

Sandbox

Local Credentials

而不是：

Production Credentials

---

二十六、第十二步：建立 Architecture Decision Record

Agent 最大的问题之一是：

不知道为什么以前要这么设计。

例如它看到：

项目没有 Redis Lock。

可能觉得：

我给你加一个分布式锁。

但团队可能早就讨论过：

因为部署环境和维护复杂度，
明确决定不使用 Redis Lock。

这种信息应该放进：

docs/decisions/

比如：

003-no-redis-lock.md

内容：

# ADR-003: Do Not Use Redis Distributed Locks

## Context

Inventory concurrency requires coordination.

## Decision

Use PostgreSQL row-level locking.

Do not introduce Redis-based distributed locks.

## Reason

- PostgreSQL is already the source of truth.
- Avoid additional infrastructure.
- Existing transaction model is sufficient.

## Consequence

Concurrency-sensitive code should use:

SELECT ... FOR UPDATE

这样 Codex 以后调查库存问题时，就不会突然：

npm install redis-lock

---

二十七、第十三步：项目文档必须是“可导航”的

不要只有：

docs/
  100 个 Markdown

但没有入口。

最好：

docs/index.md

类似：

# Documentation

## Start Here

Architecture:
architecture/overview.md

## Backend

backend.md

## Business

Orders:
business/order.md

Payments:
business/payment.md

Inventory:
business/inventory.md

## Data

Database:
database/schema.md

## Decisions

Architecture decisions:
decisions/

Agent 需要的不是：

更多文档

而是：

能够找到正确文档。

---

二十八、第十四步：对 Agent 友好的代码本身应该长什么样？

不仅是文档需要调整。

代码也应该更：

Agent Readable

比如：

function process(data: any) {
    ...
}

明显不如：

async function reserveInventory(
    orderId: OrderId,
    items: OrderItem[]
): Promise<InventoryReservation> {
    ...
}

后者天然包含更多语义。

所以 Agent-Friendly Code 通常也是：

Human-Friendly Code

包括：

明确类型

清晰命名

模块边界

小函数

显式错误

测试

少魔法

少隐藏副作用

---

二十九、Agent 最讨厌的项目是什么样？

大概是：

没有 Type

没有 Test

没有 README

没有架构文档

函数 2000 行

全局变量很多

数据库随便访问

错误全部 try/catch

业务规则全靠口头传承

启动靠手工

生产和开发配置混在一起

这种代码库对人类新人已经很痛苦。

对 Agent 同样痛苦。

于是 Agent 会不断：

Guess

---

三十、Agent 最喜欢什么项目？

反过来：

Type Strict

Tests

Lint

Clear Architecture

AGENTS.md

Docs

Standard Commands

Small Modules

Explicit Interfaces

Reproducible Environment

那么 Agent 的每一步都可以获得反馈。

例如：

TypeScript
告诉它类型错了

ESLint
告诉它规范错了

Test
告诉它行为错了

Architecture Rule
告诉它层级错了

Git Diff
告诉它改多了

整个项目本身就成为：

Agent Feedback System

---

三十一、推荐建立一个统一 Codex Task 模板

团队可以在：

.github/

或者：

docs/task-template.md

放：

# Task

## Goal

## Current Behavior

## Expected Behavior

## Relevant Modules

## Constraints

## Investigation

## Validation

## Definition of Done

## Risks

以后无论谁给 Codex 发任务，都按这个格式。

这样长期下来：

Prompt Quality

会非常稳定。

---

三十二、一个完整实战：修复库存超卖

假设线上出现：

库存只有 1。

两个请求同时下单。

两个订单都成功。

不要直接：

修复库存超卖。

推荐 Task：

# Goal

Fix inventory overselling.

# Current Behavior

When stock=1,
two concurrent checkout requests
can both create successful orders.

# Expected Behavior

Only one order may succeed.

The other request must return:

OUT_OF_STOCK

# Constraints

- PostgreSQL is the source of truth.
- Do not introduce Redis.
- Do not modify API response format.
- Do not add a distributed lock service.
- Follow existing transaction patterns.

# Investigation

Before changing code:

1. Locate inventory deduction.
2. Locate transaction boundaries.
3. Check database isolation level.
4. Check whether row locking exists.
5. Read inventory tests.
6. Read order creation tests.
7. Check docs/decisions for concurrency rules.

First explain the root cause.

# Implementation

Implement the smallest correct fix.

# Validation

Add a concurrency regression test:

initial stock = 1

request A + request B concurrently

Expected:

one success
one OUT_OF_STOCK
final stock = 0

Run:

pytest tests/inventory
pytest tests/order
ruff check .
mypy app

# Review

Review the final diff for:

- deadlocks
- transaction leakage
- retry behavior
- race conditions
- backward compatibility

# Final Output

Report:

1. Root cause
2. Changed files
3. Implementation
4. Tests
5. Remaining risks

这就是一个真正适合 Coding Agent 的任务。

---

三十三、整个流程可以总结成一个 Agent Engineering Loop

最终工作流：

Human Requirement
        ↓
Task Specification
        ↓
AGENTS.md
        ↓
Relevant Documentation
        ↓
Agent Investigation
        ↓
Plan
        ↓
Implementation
        ↓
Compiler / Type Check
        ↓
Tests
        ↓
Lint
        ↓
Git Diff
        ↓
AI Review
        ↓
Human Review
        ↓
Merge

这里的关键点是：

LLM 并不是唯一组件。

真正决定最终质量的是整套系统。

---

三十四、一个公式理解 Codex 工程效率

可以简单抽象：

Codex Effectiveness
=
Model
×
Repository Quality
×
Context Quality
×
Task Quality
×
Tool Feedback
×
Validation

假设模型：

10

但是：

Repository Quality = 2

Context Quality = 2

Validation = 1

最后结果依然不会特别稳定。

反过来，如果项目：

结构清晰

规则明确

测试完整

Prompt 明确

验证自动化

即使面对大型任务，Agent 成功率也会明显提高。

---

三十五、最后给一份可以直接复制的 AGENTS.md

如果不想从零写，可以从下面这版开始：

# Project Instructions

## Goal

Make the smallest correct change that satisfies the task.

Prefer correctness, consistency, and maintainability
over unnecessary refactoring.

## Before Editing

For non-trivial tasks:

1. Understand the requirement.
2. Locate relevant modules.
3. Read related tests.
4. Search for similar existing implementations.
5. Check relevant documentation.
6. Identify the root cause before fixing bugs.

Do not immediately edit code if the current behavior
is not yet understood.

## Architecture

Follow existing architecture.

Do not introduce a new architectural pattern
when an existing pattern can solve the problem.

Prefer existing:

- services
- repositories
- utilities
- components
- error types
- test helpers

## Scope

Keep changes focused.

Do not:

- refactor unrelated code;
- rename unrelated files;
- reformat entire files;
- upgrade dependencies;
- reorganize directories;
- modify generated files;

unless required.

## Dependencies

Do not add a new dependency unless:

1. the task cannot reasonably be completed without it;
2. there is no existing equivalent dependency;
3. the reason is explained.

## Bug Fixes

For bugs:

1. reproduce the issue;
2. identify the root cause;
3. add a regression test when practical;
4. confirm the test fails before the fix;
5. implement the smallest correct fix;
6. confirm the test passes after the fix.

Never weaken tests just to make them pass.

## Testing

Run the narrowest relevant test first.

After implementation, run:

- related unit tests;
- related integration tests;
- lint;
- type checking.

Run the full test suite when practical.

Do not claim completion when required validation fails.

If a test cannot be executed,
state the exact reason.

## Git

Before finishing:

1. inspect git status;
2. inspect git diff;
3. ensure no unrelated files changed;
4. check for accidental generated files;
5. check for secrets.

## Security

Never:

- expose credentials;
- commit secrets;
- access production data unnecessarily;
- deploy production;
- delete production resources;
- rotate keys;
- publish packages;

without explicit human approval.

## Review

Before finishing, review your own diff for:

- logic errors;
- regression;
- security issues;
- missing error handling;
- race conditions;
- null handling;
- backward compatibility;
- missing tests.

Fix confirmed issues and rerun validation.

## Definition of Done

A task is complete only when:

- requested behavior is implemented;
- scope remains focused;
- relevant tests pass;
- lint passes;
- type checking passes;
- final diff has been reviewed.

## Final Response

Summarize:

1. What changed
2. Why
3. Files changed
4. Validation performed
5. Test results
6. Remaining risks

这份模板不一定适合所有项目。

但是它提供了一个非常好的起点。

---

三十六、结语：AI 编程真正进入的是“工程化阶段”

早期使用 ChatGPT 写代码，我们关心的是：

它会不会写？

后来开始关心：

它写得准不准？

到了 Codex 和 Coding Agent 阶段，问题正在继续变化：

它能不能理解项目？

能不能自己调查？

能不能遵守工程规范？

能不能运行代码？

能不能发现失败？

能不能自己修复？

能不能通过测试？

能不能控制修改范围？

能不能安全地操作环境？

所以今天真正值得优化的，已经不仅仅是 Prompt。

而是一整套：

Repository
+
AGENTS.md
+
Documentation
+
Task Specification
+
Tooling
+
Tests
+
Review
+
Permissions

从这个角度看，Codex 最终可能会倒逼很多团队重新改善自己的软件工程基础设施。

因为一个：

Agent-Friendly Repository

往往同时也是一个：

Developer-Friendly Repository

代码结构更清晰。

业务规则更明确。

测试更完整。

开发命令更统一。

架构决策有记录。

新开发者更容易接手。

AI Agent 也更容易理解。

这可能才是 ChatGPT、Codex 和 Agentic Software Engineering 对软件开发带来的一个更深层变化：

未来优秀的软件项目，不仅需要让人能够理解，也需要让 Agent 能够理解、执行和验证。

而 AGENTS.md，可能只是这个变化的开始。