AGENTS.md 프로젝트 규칙

Codex 학습 목차로 돌아가기

이 글에서 완성할 것

규칙 파일은 테스트 명령이나 데이터 보존 조건처럼 매번 반복하던 프로젝트 요구를 저장합니다. 비밀번호 보관소가 아니며 네트워크나 파일 권한을 늘리지 않습니다. 권한 설정은 권한과 샌드박스를 참고하세요. 모든 작업을 허용한다는 문장만으로 실행 환경이 바뀌지는 않습니다.

시작 전 준비

할 일 실습 자료를 내려받아 압축을 풀고 expected 폴더를 복사해 codex-practice로 이름을 바꿉니다. 이 글은 완성된 참고 버전을 사용하므로 미완성 필터를 규칙 문제로 오해하지 않습니다. 데이터는 가상입니다. 개인 프로젝트나 전역 규칙은 아직 수정하지 마세요.

폴더 바로 아래에 index.html, style.css, app.js, core.mjs, core.test.mjs가 있어야 합니다. 사용할 수 있는 Codex 데스크톱 앱 또는 CLI를 준비합니다. 테스트는 Node.js, 로컬 미리보기는 Python 3를 사용합니다. 먼저 규칙 파일을 작성하고 도구 준비는 첫 프로젝트에서 나중에 진행해도 됩니다.

규칙을 읽는 위치와 순서

Codex는 전역 지침과 프로젝트 지침을 결합합니다. 전역 기본 위치는 사용자 홈 아래 .codex이며 CODEX_HOME을 설정했다면 그 위치를 사용합니다. 프로젝트에서는 루트부터 현재 작업 디렉터리까지 탐색합니다. 작업 위치에 가까운 지침이 앞선 조건을 구체화할 수 있지만 모든 하위 폴더를 한꺼번에 읽는 것은 아닙니다.

같은 디렉터리에서는 AGENTS.override.md, AGENTS.md, 설정된 대체 이름 순으로 찾습니다. 같은 위치의 후보 파일을 모두 더하지는 않습니다. README.md는 보통 사람에게 프로젝트를 설명하는 문서이며 Markdown이라는 이유만으로 규칙 파일이 되지 않습니다. 프로젝트 지침의 합산 크기는 기본 32 KiB까지입니다. 제한을 늘리기 전에 중복 설명과 큰 예제를 정리하세요.

이번에는 실습 프로젝트의 AGENTS.md만 추가합니다. 전역 선호는 다른 프로젝트에도 영향을 줍니다. 정말 공통으로 쓸 요구인지 확인한 뒤 config.toml 설정과 공식 문서를 살펴보세요.

프로젝트 루트를 찾을 수 없으면 규칙 탐색은 현재 디렉터리만 확인합니다. Git을 쓰지 않는 이 실습은 codex-practice 바로 아래에서 시작하세요. 임의의 하위 폴더에서 시작해도 상위 규칙을 찾는다고 가정하면 안 됩니다. 저장소 안의 비교는 규칙 적용 범위, 긴 문서 분리는 규칙과 참고 자료의 역할을 참고하세요.

1단계: 경로와 파일 이름 확인

Windows 탐색기에서 codex-practice를 열고 파일 확장명을 표시한 다음 일반 텍스트 편집기로 AGENTS.md를 만듭니다. AGENTS.md.txt가 아닌지 확인하세요. 폴더에서 PowerShell을 열어 아래 명령을 실행하면 실습 파일 다섯 개가 보여야 합니다. expected의 상위 폴더라면 올바른 폴더로 먼저 이동합니다.

Get-Location
Get-ChildItem -Name

macOS에서는 실습 폴더에서 터미널을 열거나 Terminal에 cd를 입력한 다음 Finder의 폴더 경로를 끌어 놓습니다. Linux는 파일 관리자의 터미널에서 열기를 사용합니다. 두 환경 모두 아래 명령으로 경로를 확인하고 일반 텍스트 파일을 만듭니다. Linux에서도 찾을 수 있도록 대소문자를 정확히 유지합니다.

pwd
ls -a

이미 AGENTS.md가 있다면 먼저 읽고 원문을 보존한 채 필요한 항목만 합칩니다. 새 실습 복사본에는 이 파일이 없습니다. 절차를 그대로 따라 하려고 다른 프로젝트의 규칙을 덮어쓰지 마세요.

2단계: 실행 가능한 규칙 작성

아래가 전체 파일이며 추가 패키지는 필요 없습니다. 다섯 언어에서 같은 내용을 쓰도록 영어 예제를 사용하지만 자신의 규칙은 편한 언어로 작성할 수 있습니다. 명령이 실제로 존재하고 범위가 구체적이며 결과를 관찰할 수 있어야 합니다.

# Small Steps practice instructions

- Work only inside this practice folder.
- Keep the existing task data format and localStorage key unchanged.
- Do not add packages or external network requests for this exercise.
- Run `node --test core.test.mjs` after changing JavaScript.
- After changing HTML or CSS, check the page at 390px and 1280px widths.
- Preserve visible keyboard focus and accessible form labels.
- In the final response, list changed files, checks run, and checks not run.
- Say why a check could not be run; do not report it as passed.

품질을 좋게 하라는 말만으로는 검증 기준이 없습니다. 이 예제는 실제 테스트 명령, 화면 너비, 키보드 포커스, 보고 내용을 기준으로 만듭니다. npm test로 바꾸지 마세요. 이 자료에는 package.json이 없으므로 존재하지 않는 명령을 쓰면 매번 실패합니다.

3단계: 새 세션에서 로드 확인

파일을 저장한 뒤 실습 폴더에서 새 Codex 세션을 시작합니다. 데스크톱에서는 해당 프로젝트를 선택해 새 작업을 만들고, CLI에서는 기존 대화를 종료한 다음 같은 폴더에서 codex를 다시 실행합니다. 지침은 세션 시작 때 모으므로 기존 대화 중 파일을 바꿨다고 다시 읽었다고 판단하면 안 됩니다.

List the AGENTS.md or AGENTS.override.md files loaded for this task.
Summarize the rules that apply to this practice folder.
Do not modify any files. If you cannot establish a source, say so.

실습 폴더의 AGENTS.md 경로와 테스트, 화면, 보고 요구를 확인할 수 있어야 합니다. 답변은 단서이며 파일을 직접 열어 내용과 대조합니다. 올바른 경로 없이 요청만 반복한다면 수정을 진행하기 전에 작업 폴더와 파일 이름부터 고칩니다.

4단계: 작은 변경으로 행동 확인

In index.html, change the main heading to "Small steps, clear progress."
Keep the todo behavior, stored data, and other visible text unchanged.
Follow the project instructions. Show the changed file and report the checks.

차이는 주로 index.html의 제목 문자열이어야 합니다. Windows는 py -m http.server 4173 --bind 127.0.0.1, macOS/Linux는 python3 -m http.server 4173 --bind 127.0.0.1로 미리보기를 시작합니다. http://127.0.0.1:4173에서 제목, 두 화면 너비, Tab 포커스를 확인하고 Read를 추가해 완료 처리합니다. Codex에 브라우저 도구가 없다면 직접 확인하고 실행하지 못한 검사를 보고하도록 합니다.

정상 사례는 요청한 범위만 바뀌고 기존 데이터가 남으며 보고가 규칙을 따르는 것입니다. 경계 사례는 브라우저가 없는 환경입니다. 제한과 수동 확인 항목을 밝혀야 하며 화면이나 통과 결과를 만들어 내면 안 됩니다. 규칙이 있어도 실제 파일과 도구로 증거를 확인해야 합니다.

규칙을 증거와 하나씩 연결

제목만 바꾸면 “JavaScript 변경 후”라는 조건은 충족되지 않습니다. 이것만으로 테스트를 빠뜨렸다고 판단하지 마세요. 명령 실행 가능 여부는 아래 읽기 전용 요청으로 별도 확인할 수 있습니다. expected 사본은 통과 3개, 실패 0개가 예상됩니다. 이는 명령과 보고를 확인하는 것이며 모든 규칙 분기를 실측한 것은 아닙니다.

Run node --test core.test.mjs from this practice folder without editing any files.
Report the working folder, command, exit status, and test counts.
If the command cannot run, quote the error and mark the check NOT RUN.

문제 해결과 복원

규칙을 찾지 못하면 선택한 프로젝트, 실제 확장명, 빈 파일, 같은 위치의 override를 차례로 확인합니다. Windows에서 읽힌 다른 대소문자 이름이 Linux에서도 된다는 보장은 없습니다. 수정 후 새 세션에서 다시 확인합니다.

규칙이 충돌하면 더 깊은 폴더와 전역 override를 포함해 출처의 계층을 확인합니다. 공통 조건과 이 폴더만의 예외를 구분하고 서로 부정하는 문장을 더하지 마세요. 하위 디렉터리 탐색은 후속 글에서 다루며 이번에는 프로젝트 파일 하나를 유지합니다.

테스트를 실행하지 않았다면 JavaScript를 실제로 바꿨는지 먼저 확인합니다. 이어서 node --version과 현재 폴더의 core.test.mjs를 확인하세요. 런타임이 없는 문제와 지침을 읽지 못한 문제는 다릅니다. 통과할 것 같다는 말 대신 실제 오류를 요청합니다.

Ctrl+C로 미리보기를 중지합니다. 제목은 이번에 바꾼 부분만 복원합니다. 새로 만든 AGENTS.md는 실습 폴더 밖으로 옮겨 보관할 수 있습니다. 기존 파일에 추가했다면 자신의 항목만 되돌립니다. 규칙을 제거해도 이미 수행한 파일 변경은 취소되지 않습니다. 복원된 지침 역시 새 세션에서 확인합니다.

추가 실습과 출처

최종 답변에서 수동 확인 사항을 먼저 쓰라는 규칙을 추가한 뒤 새 세션에서 다른 제목 변경을 요청합니다. 출처를 찾고 차이가 요청한 제목에만 있으며 보고 순서가 바뀌면 성공입니다. 추가한 규칙을 제거하고 다음 새 세션과 비교하세요.

확인일은 2026-09-14입니다. 탐색과 크기 제한은 AGENTS.md 공식 문서로 확인했습니다. 실습 웹사이트와 데이터 테스트는 Windows/Edge에서 검증했지만 macOS, Linux 또는 Codex 지침 로드 자체를 실기기로 시험했다는 뜻은 아닙니다. 다음으로 Markdown, 작업 인계, Skills를 읽을 수 있습니다.

Codex 학습 목차로 돌아가기

자세한 설명 보기

Global to Project to Working directory

• AI 도구
• 튜토리얼
• Codex