Quick Reference

# AGENTS.md

## Repository map
- Web/: Next.js application
- tools/: content validation scripts

## Run and test
- Content: npm --prefix Web run content:check
- Build: npm --prefix Web run build

## Constraints
- Do not edit generated files under Web/generated/.

## Done when
- Run the affected validation command.
- Inspect the final diff.

AGENTS.md에는 Codex가 이 저장소에서 지금 실행할 판단을 넣는다. 배경 역사나 팀 위키가 아니라, 파일을 찾을 위치, 실행할 검증, 바꾸면 안 되는 범위, 완료를 판단할 증거가 핵심이다.

무엇을 적을지

Repository map에는 디렉터리 이름보다 소유 경계와 진입점을 적는다. Run and test에는 실제로 통과시켜야 하는 명령을, Constraints에는 public API, generated output, migration처럼 실수 비용이 큰 금지 또는 확인 조건을 둔다. Done when은 수정만 마친 상태와 검증까지 끝난 상태를 구분한다.

반복되는 실패                    -> AGENTS.md에 남길 정보
다른 package의 test를 실행한다     -> 이 경로에서 쓸 정확한 검증 명령
생성 파일을 직접 수정한다          -> 원본과 생성 명령의 위치
변경 범위가 넓어진다               -> 수정 가능한 경로와 보존할 계약
테스트 없이 완료로 판단한다        -> 완료 조건과 검토 증거

Code Review에만 적용할 판단은 ## Code Review Rules에 둔다. 이 규칙은 호환성, 데이터 경계, 위험한 side effect와 안전한 예외를 설명한다. formatting, lint처럼 기계적으로 판정할 수 있는 항목은 review 규칙이 아니라 CI에 둔다.

작고 최신으로 유지하는 방법

AGENTS.md는 Codex가 작업을 시작할 때 읽는 guidance이지, workspace 접근권을 부여하거나 sandbox를 강제하는 보안 정책은 아니다. 강제해야 할 권한 경계는 requirements와 approval 정책에 둔다. 한 파일에 모든 팀 문서를 넣으면 뒤쪽의 실행 규칙이 묻히고, 이미 바뀐 명령이 계속 실행될 수 있다.

좋은 지침: npm --prefix Web run content:check를 실행한다.
약한 지침: 항상 품질을 중요하게 생각한다.

좋은 지침: Web/generated는 생성 산출물이다.
약한 지침: 생성 파일은 조심해서 다룬다.

검증 명령이나 배포 흐름을 바꿨다면 AGENTS.md도 같은 변경에서 갱신한다. 새 지침은 repository root에서 Codex가 실제로 읽는지 확인하고, 하위 package에만 적용할 내용은 그 directory 가까이에 둔다.