내가 AGENTS.md를 작성하는 방법
Codex CLI
요즘 프로젝트 개발에 Codex CLI를 활용하는 이유는 다음과 같다.
특정 프로젝트를 작업할 때 Claude Code는 종종 사용량을 초과한 것과 다르게 Codex CLI는 ChatGPT Plus 요금제만으로도 토큰 사용량 초과 걱정 없이 충분하게 활용할 수 있었다.
타 CLI 기반 AI 개발 도구에 비해서 요구사항을 더 정확하게 구현하고 꼭 필요한 작업만 진행하기 때문에 코드를 검토하는 시간을 줄일 수 있다.
반복적인 코드 작성을 자동화할 수 있어서 서비스 개발에 드는 시간을 절약할 수 있고 서비스에 필요한 기능 및 구현 방법 탐색, 개발에 필요한 도구 학습에 시간을 더 투자할 수 있다.
AGENTS.md
Codex CLI와 같은 AI 개발 도구는 AGENTS.md를 작성하여 AI가 어떻게 작업해야 할지 지시할 수 있다.
지시사항을 작성하지 않으면 다양한 문제점을 맞이할 수 있다.
개발자들이 자주 유발하는 안티패턴을 따라하게 된다.
실제로 작동하지 않는 코드를 그럴 듯하게 작성한다.
아무것도 하지 않았는데도 작업을 마쳤다고 답변하는 상황도 있었다.
프로젝트 요구사항에 필요하지 않은 코드까지 작성하게 되면 디버깅하는 시간도 길어지게 된다.
이런 시행착오를 줄이기 위해서 올바른 지시사항을 작성하는 방법을 계속 조사하게 되었다.
현재 AGENTS.md에 작성한 프롬프트 예시는 다음과 같다.
당신은 소프트웨어 엔지니어, 프론트엔드 개발자, 백엔드 개발자, 웹 서비스 개발 팀 매니저입니다.
한국어로 작업을 진행해주세요.
자료를 조사하기 위해 인터넷 검색 및 기타 자료 조사를 적극적으로 활용해주세요. 작업이 주어지면 단계적으로 작업을 분할하세요.
작업 태도는 낙관적 0, 객관적 10 이면 9-10의 태도를 유지해주세요.
작업을 진행하실 때 부족한 지식 및 개념이 있는지 검토해주세요. 생소하거나 관련 지식 및 경험이 없는 개념을 발견하시면 개념의 정의, 기능, 목적, 예시, 기대효과 등의 필요하다고 생각하는 정보를 전부 조사하셔서 작업에 종합적으로 활용하세요. 조사한 정보 내에도 또다른 생소한 개념이 있다면 해당 개념에 대해서도 동일한 작업을 진행해주세요.
작업을 시작하기 전에 작업을 수행하기 위한 3가지 방법을 조사하시고 생각해주세요. 그리고 3가지 중에서 어떤 방법을 사용해야 프롬프트 및 서비스의 요구사항을 충족시킬 수 있을지 검토해주세요. 선정된 방법이 과연 프롬프트를 작성한 사용자의 요구사항를 충족시키는지 다시 한번 검토해주세요. 검토 후 부족한 부분을 찾아서 개선할 수 있는 방법을 조사하세요. 이러한 방법 조사, 방법 선택, 검토 작업을 최대 5번 반복 후 작업을 진행해주세요.
작업을 수행하면 해당 작업에 대해서 개선해야 할 사항이 있는지 한번 더 점검해주세요. 개선 사항을 3가지 제안한 다음 어떤 방식으로 개선해야 프로젝트를 더 안전하고 더 좋은 서비스를 구현할 수 있을지 생각해주세요. 그리고 개선 방안을 선택하여 프로젝트에 반영해주세요.
인터넷 검색을 할 때에는 각각의 웹 문서가 신뢰성과 최신성을 전부 갖추고 있는지 먼저 판단해주셔야 합니다. 왜냐하면 요즘 인터넷에는 검색 엔진 상위 랭크를 노리고 AI로 양산한 SEO 최적화된 웹 문서가 너무 많습니다. 그래서 자료의 최신성 뿐만 아니라 신뢰성까지 파악해주셔야 합니다.
추가적인 요청 사항이 발생했을 때도 동일한 프로세스를 진행하세요.
역할
AI가 어떤 역할을 갖고 있어야 하는지 정의한다. 역할을 부여하여 특정 전문가의 관점에서 답변을 작성하도록 유도할 수 있다.
- 프론트엔드 개발
당신은 소프트웨어 엔지니어, 프론트엔드 개발자입니다.
언어
대화, 코드, 주석, 커밋 메시지 등 용도에 맞는 원하는 언어를 지정할 수 있다. 예를 들어 한국어로 설명하면서 커밋 메시지는 영어로 작성하도록 규칙을 작성할 수 있다.
목적
프로젝트를 정확하게 명시하지 않으면 필요하지 않은 코드가 생성되는 경우가 있었고 코드 검토 시간이 늘어나게 된다.
내가 어떤 프로젝트를 개발하고 있으며 이 프로젝트를 구현하기 위해 어떤 기능이 필요한지 명시한다.
방식
AI가 어떤 답변을 생성할지 미리 알 수 없기 때문에 다음과 같은 지시사항을 추가했다.
해결해야 하는 작업에 대해서 단계적으로 작업을 분할한다. 목표를 달성하기 위해 필요한 작업이 무엇인지 추론하는 단계를 포함시킨다.
특정 작업에 대해서 여러 개의 답변을 생성한 다음 목표에 제일 가까운 답변을 선택하도록 했다.
선택한 답변에 대해서도 사용자가 요구하는 작업을 진행하기에 부족함이 없는지 한번 더 체크한다.
이 과정을 여러 번 반복해서 최대한 작업의 부작용을 줄인다.
자료 조사
AI가 학습한 데이터는 한계가 있기 때문에 데이터에서 생소하거나 경험이 없는 지식이 있으면 웹 검색을 통해서 따로 학습하도록 지시할 필요가 있었다.
그래서 AGENTS.md를 세팅할 때도 인터넷 검색을 할 수 있도록 인터넷을 통해 자료를 조사하라는 지시를 추가했다.
요즘 인터넷에는 AI를 통해서 컨텐츠 생성을 자동화한 블로그가 많고 그런 블로그들이 가치있는 정보를 제공한 경우는 없었다.
그리고 개발 생태계는 지속적으로 발전하기 때문에 AI가 옛날 자료를 기반으로 작업하게 되면 코드는 정상적으로 보여도 실제로 작동하지 않는 문제도 있었다.
자료의 최신성 및 신뢰성까지 전부 체크하도록 프롬프트를 작성했을 땐 블로그보다는 공식문서나 깃허브 레포를 탐색하는 빈도가 증가하는 것처럼 보였다.
추가 지시사항
프로젝트를 진행하면서 AI가 일관된 작업 패턴을 유지하도록 하기 위해 추가적인 지시사항을 작성할 수 있다.
서비스에 필요한 기능 정의 및 추가적으로 필요한 기능 조사
서버 컴포넌트 & 서버 액션에서 사용자 검증 방식
백엔드 프로젝트 세팅 및 NestJS 베스트 프랙티스 패턴을 조사하고 반영
비밀 관리에 환경 변수 파일 사용