나는 프로젝트를 진행할 때 Codex를 사용한다.
프로젝트 루트에 AGENTS.md 파일을 두면 Codex는 작업을 시작하기 전에 해당 문서를 참고하여 작업 방향과 제약 조건을 설정한다. 따라서 AGENTS.md는 단순한 참고 문서가 아니라, AI의 행동을 정의하는 일종의 운영 규칙에 가깝다.
프로젝트마다 요구 사항은 다르기 때문에 세부 지침은 달라진다. 그러나 여러 프로젝트를 운영하면서 공통적으로 반복되는 문제가 있었다.
언어 혼입, 과도한 추측 수정, 불필요한 파일 변경, 임시 코드 작성 등이다.
이를 방지하기 위해 나는 모든 프로젝트에 공통으로 적용하는 ‘부칙’을 따로 두고 있다.
부칙 정리
[언어 및 표현 규칙]
- AI 처리 과정 메시지와 응답 메시지는 모두 한국어로 작성한다.
- 처리 과정 메시지를 제외한 모든 응답에는 존댓말을 사용한다.
- 응답에 한글 인코딩 깨짐 또는 타 언어 혼입이 보이면 즉시 전체 문장을 한국어로 다시 작성한다.
- UTF-8 인코딩이 깨지지 않았는지 확인한다.
��등의 깨진 문자열이 포함되면 전체 문장을 재작성한다.
[코드 변경 원칙]
- 모든 주석은 한국어로 작성한다. 코드 변경 시 주석도 함께 수정한다.
- 사용자가 요청한 범위를 벗어난 파일은 수정하지 않는다.
- 이해하지 못한 요구 사항이 있으면 반드시 사용자에게 되묻는다.
- 디버그 로그는 문제가 해결되면 반드시 삭제한다.
- 추측성 수정은 금지한다. 원인을 모르면 수정하지 않는다.
[보안 및 운영 원칙]
- 보안에 취약한 코드는 특별한 지시가 없다면 사용하지 않는다.
- 간단하지 않은 문제는 웹 검색을 통해 최신 해결책을 확인한다.
- 이 프로젝트는 프로덕션 환경이다. 오류 수정을 위해 임시 우회 코드를 작성하지 않는다.
- 코드 작업 시
docs/폴더의 모든 Markdown 문서를 숙지하고 규칙을 준수한다. 해당 폴더가 없으면 이 지침은 적용하지 않는다.
정답은 없다.
너무나 다양한 AI가 출시되었고 앞으로도 계속 출시 될 수 있고 사용하는 사람도 너무나 다양하기 때문에,
AI의 최적화에는 정답이 없다.
그러나 명확한 제약과 일관된 규칙은 결과물의 품질을 눈에 띄게 안정시킨다.
각자 자신만의 기준을 정의해 두는 것이 장기적으로 가장 효율적인 방법이라고 생각한다.
시간을 내어 나만의 기준을 정의해 보는건 어떨까. 😃
복사용 Codex AGENTS.md 부칙
위 내용을 복/붙하기 편하게 정리해둔다.
## 부칙
1. AI 처리 과정 메시지와 응답 메시지는 모두 한국어로 작성한다.
2. 처리 과정 메시지를 제외한 모든 응답에는 존댓말을 사용한다.
3. 응답에 한글 인코딩 깨짐 또는 타 언어 혼입이 보이면 즉시 한국어 문장으로 정정한다.
- 응답 생성 시 **한글(UTF-8) 인코딩이 깨지지 않도록 확인**하고, 깨진 문자열(예: `��`) 또는 타 언어 문장이 섞이면 즉시 전체 문장을 한국어로 다시 작성한다.
4. 한국어로 주석 작성하고 내용이 바뀌면 주석도 변경한다.
5. 사용자가 요청한 작업 범위외 파일은 수정하지 않는다.
6. 이해하지 못한 요구 사항이 있으면 반드시 사용자에게 되물어본다.
7. 디버그 로그는 문제가 해결 되었다면 반드시 삭제한다.
8. 보안에 취약한 코드는 특별한 지시가 없다면 사용 금지한다.
9. 추측성 수정은 절대 금지한다. 원인을 모르면 수정 금지한다.
10. 간단하지 않은 문제라면 웹 검색을 통해 최신 해결책을 검색한다.
11. 이 프로젝트는 프로덕션이다. 오류 수정을 위해 우회하는 임시 코드를 작성 금지한다.
12. 코드 작업 시 `docs/` 폴더의 모든 Markdown 문서를 숙지하고, 해당 문서에 정의된 규칙을 준수한다. `docs` 폴더가 없을 경우 이 지침은 무시해도 된다.