01-AGENTS.md项目规则

全局层（~/.codex 或 CODEX_HOME）
  -> 项目根目录
  -> 根目录到当前目录之间的每一级
  -> 当前目录
  -> 从上到下合并，越近越具体

# 个人默认规则

- 开始修改前先读取相关规则、README 和测试配置。
- 修改后检查 diff，不要只根据摘要判断完成。
- 未经明确确认，不要提交、推送、删除数据或访问生产系统。
- 输出命令结果时隐藏令牌、Cookie、邮箱和内部链接。

shop/
├── AGENTS.md
├── src/
│   ├── AGENTS.md
│   └── payments/
│       └── AGENTS.override.md

全局层
shop/AGENTS.md
shop/src/AGENTS.md
shop/src/payments/AGENTS.override.md

pwd
git rev-parse --show-toplevel
git status --short

Get-Location
git rev-parse --show-toplevel
git status --short

AGENTS.override.md
AGENTS.md
project_doc_fallback_filenames 中的备选名称

rg --files -g 'AGENTS.md' -g 'AGENTS.override.md' -g 'TEAM_GUIDE.md' -g '.agents.md'

Get-ChildItem -Path . -Recurse -File -Include AGENTS.md,AGENTS.override.md,TEAM_GUIDE.md,.agents.md

全局规则

仓库根规则

src 规则

当前服务规则

- 默认使用项目提供的包管理器。

- JavaScript 依赖统一使用 pnpm，不要改用 npm 安装。

- 本目录是 Python 服务，使用 uv 和 pytest；不要执行前端命令。

- 所有项目都使用 pnpm。

- 前端目录使用 pnpm。
- Python 服务目录使用 uv；测试使用 pytest。
- 跨运行时任务分别执行各目录的检查。

~/.codex/AGENTS.md
repo/AGENTS.md
repo/backend/AGENTS.override.md

# backend/AGENTS.override.md

## 临时集成测试规则

- 本次只调用测试替身，不要连接生产或共享开发数据库。
- 验证使用 `make test-integration-local`。
- 任务结束后移除此文件，不要写入临时凭据。

# services/payments/AGENTS.md

## 支付服务

- 运行时为 Python 3.12，依赖使用 uv 管理。
- 单元测试运行 `uv run pytest services/payments/tests`。
- 支付流程必须覆盖重复回调、超时和幂等场景。
- 不要修改已经发布的迁移；新增迁移前先说明回滚方案。
- 本地验证只使用测试网配置，不要读取生产密钥。

# 项目或组件名称

## 项目范围
- 本目录负责什么
- 明确不负责什么

## 工作区入口
- 关键代码、测试和配置路径
- 生成文件或不可手改文件

## 常用命令
- 安装、开发、测试、lint、类型检查、构建

## 修改约定
- 代码放置、命名、API 和兼容性要求
- 测试位置、依赖、生成代码和迁移要求

## 验收标准
- 必须运行的命令
- 必须检查的行为
- 失败时如何报告

## 禁止和需确认的操作
- 只读目录、敏感系统和破坏性命令
- 外部数据和凭据边界

- 测试要做好。
- 代码质量很重要。

- 修改业务逻辑后运行 `pnpm test -- --runInBand`。
- 新增公共函数时补充边界测试；失败时报告失败命令和首个相关错误。

- 不要手工修改 `pnpm-lock.yaml`；依赖变更使用 `pnpm add` 生成。
- 不要修改已发布迁移；需要变更时新建迁移并说明回滚方案。
- 修改 CI 配置前先列出影响的工作流和验证方式。

## 常用命令

- 安装依赖：`pnpm install --frozen-lockfile`
- 单元测试：`pnpm test`
- 类型检查：`pnpm typecheck`
- 生产构建：`pnpm build`

- 在仓库根目录执行 `make test-api`。
- 集成测试前启动测试容器，不要把请求发到生产地址。
- 缺少 `TEST_DATABASE_URL` 时停止并报告，不要读取 `.env.production`。

## 验证分层

- 小范围逻辑修改：先运行相关测试，再运行 `pnpm lint`。
- 跨模块修改：运行相关测试、`pnpm typecheck` 和 `pnpm build`。
- 提交前：运行 `pnpm verify`；未运行时必须说明原因。

- 命令失败时不要删除测试、跳过检查或修改 CI 伪造绿色结果。
- 报告失败命令、退出码和首个相关错误，区分环境缺失与代码回归。
- 需要网络、凭据或外部服务时，先说明依赖并等待确认。

## 验收标准

- `POST /api/orders` 缺少商品时返回 400，不创建订单。
- 新增行为由 `pnpm test -- order` 覆盖。
- `pnpm lint` 和 `pnpm typecheck` 通过。
- 不改变成功响应中的既有字段和状态码。
- 无法运行集成测试时，报告缺少的服务和未验证风险。

- 本目录修改应保持 `src/payments` 外的文件不变，除非任务明确说明。
- 完成后检查 `git diff --stat` 和 `git diff --name-only`。
- 需要扩大范围时先报告原因，不要默默修改其他服务。

mkdir agents-md-demo
cd agents-md-demo
git init
mkdir -p services/payments

New-Item -ItemType Directory agents-md-demo | Out-Null
Set-Location agents-md-demo
git init
New-Item -ItemType Directory services/payments -Force | Out-Null

git rev-parse --show-toplevel

# agents-md-demo

## 项目范围

这是演示规则发现和局部覆盖的最小项目。

## 常用命令

- 根目录检查：`printf 'root-check\\n'`
- 修改后检查 `git diff --check`。

## 约束

- 不新增依赖，不删除文件，不访问外部服务。
- 完成时报告修改文件和实际检查。

# services/payments

## 局部规则

- 本目录检查使用 `printf 'payments-check\\n'`。
- 修改前先阅读本目录测试。
- 不要修改 `services/payments` 之外的文件。
- 完成时说明根目录和本目录规则如何满足。

# services/payments 临时规则

## 临时验证

- 本次只运行 `printf 'override-check\\n'`，不要运行普通 payments 检查。
- 这是演示用临时 override，验证结束后删除。
- 不要修改文件，不要访问外部服务。

只读检查当前生效的项目规则。列出规则文件路径，区分根目录规则和当前目录规则；说明当前目录的验证命令。不要修改文件，不要执行命令。

请先不要修改任何文件，也不要运行有副作用的命令。
列出当前工作目录、项目根目录，以及从全局层到当前目录可能影响本任务的规则文件。
按“来源、有效规则、冲突或例外、尚未确认的内容”总结。
不要把猜测当成已加载事实。

## 验证标记

- 只读总结中必须明确写出：`agents-md-demo rules loaded`。

只检查当前规则要求的快速验证命令。执行前列出命令和预期影响；只允许执行不会写文件、不会联网的命令。执行后报告退出码。不要修改文件。

git status --short
git diff --check
git diff --stat

project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
project_doc_max_bytes = 65536

# 根目录
- 修改后检查 git diff。

# 子目录
- 修改支付逻辑后运行 pytest。

# 根目录
- 测试使用 `pnpm test`。

# 子目录
- 测试使用 `uv run pytest`。

- 本 Python 服务不使用根目录的 JavaScript 测试命令；本目录测试使用 `uv run pytest`。

- 不要使用 `npm install`；依赖安装使用 `pnpm install --frozen-lockfile`。

# <项目或组件名称>

## 项目范围

- 本目录负责：<一句话>
- 本目录不负责：<明确边界>

## 工作区入口

- 主要代码：`<path>`
- 测试：`<path>`
- 配置：`<path>`
- 生成或不可手改文件：`<path>`

## 常用命令

- 安装：`<command>`
- 开发：`<command>`
- 测试：`<command>`
- lint / 格式化：`<command>`
- 类型检查：`<command>`
- 构建：`<command>`

## 修改约定

- <代码和命名规则>
- <兼容性、依赖或迁移要求>
- <测试位置和边界场景>

## 验收标准

- <行为结果>
- <必须执行的检查>
- <必须保持不变的接口或文件>
- 失败时报告命令、错误和未验证风险。

## 禁止和需确认的操作

- 不要：<破坏性或越权操作>
- 未经确认不要：<生产、网络、数据或依赖操作>
- 不要输出：<凭据、用户数据和内部链接>

git status --short
rg --files -g 'AGENTS.md' -g 'AGENTS.override.md'
rg -n 'test|lint|typecheck|build|format' package.json pyproject.toml Makefile .github 2>/dev/null

请先读取当前目录到项目根目录的规则文件、相关脚本和测试配置。
不要修改文件。列出规则来源、适用范围、冲突和需要更新的命令。
然后给出一份只改 AGENTS.md 的最小编辑计划。

git diff --check
git diff --stat
git diff -- AGENTS.md
git status --short

git diff -- services/payments/AGENTS.md services/payments/AGENTS.override.md

确认当前位置
  -> 找全局到当前目录的候选
  -> 判断 override 和配置
  -> 理解从根到近的合并规则
  -> 写可执行命令和验收标准
  -> 用只读复述和低风险动作验证
  -> 检查 diff、状态和未验证风险