如何编写AGENTS.md：向Codex说明项目规则

摘要： AGENTS.md记录项目反复需要的工作规则。简洁保留安装命令、验证方法与变更边界，并维护其与当前代码一致。

1. 何时需要AGENTS.md

每次委托Codex，都反复说明“仓库使用其他包管理器而非npm”“不要直接修改生成文件”时，项目指导文件就有用。可将AGENTS.md视为随项目共同管理这些工作约定的文档。

OpenAI官方文档说明，Codex开始工作时读取AGENTS.md指导，并共同构建全局与项目指导。本文章示例是假想仓库草稿。应先在真实项目确认示例命令，避免直接写入。

2. 先从仓库根目录的简短文件开始

首个文件可按团队成员初次进入仓库需要的指南编写：哪些文件夹是源代码、使用什么命令运行、修改后需要哪些检查。不使用的命令或长期未更新说明，可能将任务引向错误方向。

# 프로젝트 작업 규칙

## 구조
- 화면 코드는 src/ui, 데이터 처리 코드는 src/data에 있습니다.
- generated 폴더의 산출물은 직접 편집하지 마세요.

## 변경 기준
- 기존 공개 함수의 입력과 반환 형식을 유지하세요.
- 요청과 관계없는 파일은 수정하지 마세요.
- 다른 작업자의 변경을 덮어쓰지 마세요.

## 검증
- package.json에서 현재 테스트 명령을 확인해 실행하세요.
- 실행 명령, 결과, 실행하지 못한 이유를 구분해 보고하세요.

明确知道命令时，可以将“确认后执行”替换为实际命令。尚不知道时，宜要求从项目配置查找，而不是随意规定npm test。规则应是可执行指南，而非漂亮宣言。

3. 必要时才拆分子文件夹规则

官方文档说明，会收集从项目根目录到当前工作目录路径上的指导，较近目录的指导稍后加入。每个目录适用AGENTS.override.md、AGENTS.md等查找优先顺序。存在多个文件时，实际启动位置很重要。

小仓库可能只需一个根文件。界面与服务器验证流程不同，可考虑各区域单独指导。共同规则复制到每个子文件，后续容易变成不同内容。共同约定放根目录，仅区域必要差异放子文档，更易管理。

4. 编写后确认实际应用内容

创建文件后不应结束，还需确认新任务读取哪些规则。以下是限制执行的情况下检查内容的请求示例，可在实际委托前用于发现文档错误。

현재 작업 디렉터리에 적용되는 AGENTS.md 지침을 요약해 주세요.
적용 파일의 경로와 검증 명령을 알려 주세요.
서로 충돌하거나 실행할 수 없는 지침이 있으면 설명해 주세요.
이 요청에서는 파일을 수정하거나 설치하지 마세요.

回答遗漏预期文件时，先确认工作目录与文件名。指导变化似乎未生效时，在新会话重新确认。官方说明指导在运行开始时构建，所以重新确认比推测旧会话何时应用新内容更明确。

5. 常见失败规则与修正方法

• “始终最高质量”等抽象规则： 改为保持公开API、验证命令等可检查条件。
• 不存在的测试命令： 与当前配置匹配，或说明查找位置。
• 所有任务强制冗长流程： 区分必需步骤与条件步骤。
• 文件彼此矛盾： 整理共同规则，明确子区域例外。

不要在工作指导写密码或令牌。文档放在团队共享仓库时，宜说明所需环境变量名称与检查配置的位置，而不提供秘密值。像代码变更一样审查指导差异，更容易发现旧命令与不必要例外。

6. 用有实际命令的假想仓库编写

以下是JavaScript假想项目示例，并非实际运行结果，而是具体化指导的编写示例。假设已读取README与package.json，找到开发服务器与验证命令。假想scripts存在dev、test与lint，所以文档可以使用这些名称。照搬实际仓库不存在的名称，反而会阻碍执行。

{
  "scripts": {
    "dev": "vite",
    "test": "vitest run",
    "lint": "eslint src"
  }
}

并非要求将此scripts示例覆盖项目。当前工具不同，应写下该工具既有命令。从锁文件与README确定包管理器；测试依赖特定服务或环境变量时，也记录必要条件。“在哪里运行什么命令、需要准备什么”，比单纯“执行测试”对工作者更有用。

# AGENTS.md

## 프로젝트 구조
- src/ui: 사용자 화면, src/data: 데이터 처리
- tests: 기능 검증, public: 정적 파일
- dist는 생성 산출물이므로 소스를 먼저 수정합니다.

## 실행과 검증
- 저장소 루트에서 npm run dev로 개발 서버를 실행합니다.
- 동작을 바꾸면 관련 사례를 npm test로 확인합니다.
- JavaScript 소스를 바꾸면 npm run lint도 확인합니다.
- 실행에 필요한 조건이 없으면 실패 원인을 보고합니다.
  테스트를 건너뛰고 통과했다고 표현하지 않습니다.

## 변경 기준
- 저장된 데이터 형식은 이번 요청에 포함될 때만 변경합니다.
- 기존 사용자의 정상 입력 동작을 유지합니다.
- 다른 작업자의 변경과 생성 산출물을 덮어쓰지 않습니다.

## 보고 형식
- 변경한 동작과 파일, 실제 실행한 검증, 남은 확인을 설명합니다.

这样正常工作路径先可见，比只有冗长禁止句的文档更容易找到下一命令。不需要验证的文字修改是否也要所有步骤，应按项目标准调整。规则目的是减少重复工作中的混乱，而不是增加流程数量。

7. 根目录与子文件夹分别写什么？

以同时有界面与服务器的仓库为例。下方布局按路径拆分指导：根目录保留数据格式与报告方式等共同约定，服务器文件夹记录服务器专用运行条件。相较复制相同规则至三个文件，在一处明确适用范围更易维护。

project/
  AGENTS.md
  frontend/
    AGENTS.md
  services/
    api/
      AGENTS.override.md

官方查找以项目根目录到当前工作目录的路径为标准。不能认为从根目录启动就会一次合并所有子指导。从api文件夹启动时，应检查该路径指导；在根目录委托多个区域时，可在请求中明确读取必要子指导。实际会话通过路径与内容确认应用情况最准确。

同一文件夹有AGENTS.override.md与AGENTS.md时，不能期待自动合并两份内容。官方优先查找override，每个目录最多使用一份指导。创建临时例外时，应记录目的与移除时间，避免原文不被读取。例外持续使用时，宜整理为普通指导。

# services/api/AGENTS.override.md

## API 영역의 추가 기준
- 저장소 루트의 공통 변경 기준을 유지합니다.
- API 검증은 이 영역의 README에 적힌 절차를 따릅니다.
- 데이터베이스가 필요한 검증은 연결 대상과 준비 상태를 먼저 확인합니다.
- 테스트용 데이터 변경과 운영 데이터 변경을 구분합니다.
- 데이터 형식 변경은 영향과 이전 버전 호환 여부를 보고합니다.

8. 指导读取错误时先调查路径

规则似乎未应用时，应先确认实际文件与启动位置，而不是加强措辞。Windows隐藏扩展名时，文件可能保存为AGENTS.md.txt，却显示为AGENTS.md。资源管理器显示扩展名，或如下查询名称，即可确认准确文件名。下方命令是读取文件名与当前位置的示例。

Get-Location
Get-ChildItem -Name AGENTS*
Get-Content -LiteralPath .\AGENTS.md

1. 确认当前目录是预期项目；若是其他副本，进入正确项目。
2. 确认文件名准确且内容非空。扩展名错误时，在编辑器修正。
3. 检查同一路径或上级范围是否有override，查找意外规则来源。
4. 新会话中要求总结应用文件路径与命令，不应仅凭旧会话回答判断新文件已生效。

也应检查是否混用全局与项目规则。全局要求所有仓库运行npm test，可能不适合Python仓库。用韩语说明或区分执行与未执行等个人偏好可放全局，但特定项目命令宜放对应仓库指导。若另设Codex主目录，即使修改默认位置，也可能读取其他配置。

9. 减少过时规则的修订清单

指导也应随项目变化更新。更换测试工具或移动源代码文件夹时，应同时修改相关命令与路径。功能变化时，如果只在对话保留绕开旧命令的方法，下次会重复相同问题。可用下方提示词先检查文档与当前配置的差异。

AGENTS.md의 경로와 실행 명령을 현재 저장소와 비교해 주세요.
존재하지 않는 파일·스크립트·생성 경로를 찾아 주세요.
항목별로 현재 근거 파일과 수정 제안을 표로 정리해 주세요.
새 규칙을 임의로 늘리지 말고 오래된 규칙의 갱신부터 제안하세요.
이 단계에서는 문서를 수정하거나 의존성을 설치하지 마세요.

审查结果应区分三类：执行命令消失，是修复实际错误的更新；引入新工具，是另一个选择；将“始终所有测试”拆为相关测试与必需检查，是工作标准调整。区分类别可减少简单更新突然扩大为工具替换或结构大改。

• 路径与命令存在于当前仓库吗？
• 是否区分条件任务与每次必需任务？
• 是否将某功能的临时要求留为永久规则？
• 失败或未执行时，能了解下一行动吗？
• 是否说明环境变量名称与准备方法，而非秘密值？

好的AGENTS.md应让新工作者阅读一个文件就能开始正常工作。宜记录当前项目常出错的选择与实际流程，而非冗长汇集编码规则。需要重复复杂业务流程时，也可考虑拆为独立技能或参考文档，而非全部放根指导。

10. 常见问题

AGENTS.md与README相同吗？ README常用于向人介绍项目，AGENTS.md整理代理工作所需指导。可通过引用必要文档，避免在两处长篇复制相同说明。

规则越多越好吗？ 重要的是当前项目需要且可应用的规则，应减少重复与冲突句子。

指导会改变执行权限吗？ 工作方法指导与实际权限配置分开。文件写明允许，不会自动扩大工具访问边界。

官方来源与确认日期： OpenAI官方文档：通过AGENTS.md提供自定义指导。2026年10月3日确认。示例路径与命令应按自己的项目调整。