AI 코딩 도구를 사용하면서 문득 이런 생각이 들었습니다.
우리는 AI에게 코드를 작성시키는 방법에는 많은 관심을 기울이면서,
정작 AI가 프로젝트를 어떻게 이해하고 어떤 원칙에 따라 작업해야 하는지를 정의하는 일에는 얼마나 신경 쓰고 있을까요?
요즘 AI 코딩 도구의 발전 속도는 놀랍습니다.
자연어로 요구사항을 전달하면 코드를 작성하고, 오류를 분석하고, 리팩터링과 테스트까지 수행합니다.
이제는 개발자가 직접 코드를 작성하는 시간보다 AI가 작성한 코드를 검토하고 방향을 결정하는 시간이 더 중요해지는 것 같습니다.
그런데 여기서 한 가지 의문이 생깁니다.
AI가 아무리 뛰어난 코드를 작성하더라도, 프로젝트의 설계 철학과 구조적 원칙을 제대로 이해하지 못했다면
과연 의도한 결과물이 될 수 있을까요?
이 질문의 중심에 AGENTS.md가 있다고 생각합니다.

AGENTS.md는 단순한 지침 파일일까 ?
처음에는 AGENTS.md를 AI 코딩 도구에 전달하는 일종의 안내문 정도로 생각하기 쉽습니다.
프로젝트 디렉터리 구조를 설명하고, 코딩 스타일을 지정하고, 수정해서는 안 되는 파일이나 작업 시 주의사항을 기록하는 용도 말입니다.
하지만 프로젝트의 규모가 커지고 AI에게 맡기는 작업이 복잡해질수록 그 의미는 달라집니다.
AGENTS.md는 단순히 AI에게 무엇을 하라고 지시하는 파일이 아니라,
AI가 어떤 기준으로 판단하고, 어디까지 개입하며, 무엇을 반드시 지켜야 하는지를 정의하는 프로젝트의 운영 원칙에 가까워집니다.
예를 들어 프로젝트가 플러그인 아키텍처를 채택하고 있다면
AI는 새로운 기능을 추가할 때 기존 코어를 수정해야 할지, 플러그인으로 분리해야 할지 판단해야 합니다.
데이터베이스 접근에 별도의 규칙이 있다면 편리하다는 이유로 그 규칙을 우회해서는 안 됩니다.
기존 기능과의 호환성, 보안 경계, 업데이트 절차, 테스트 정책 역시 마찬가지입니다.
이런 원칙이 명확하지 않으면 AI는 당장의 요청을 해결하는 데 가장 쉬운 방법을 선택할 수 있습니다.
그 결과 기능은 정상적으로 동작하지만 프로젝트 전체의 일관성은 조금씩 무너지게 됩니다.
더 우려스러운 부분은 이러한 문제가 즉시 드러나지 않는다는 점입니다.

AI의 능력보다 중요한 것은 판단의 기준이 아닐까 ?
우리는 흔히 어떤 AI 모델이 더 뛰어난지, 어떤 도구가 코드를 더 정확하게 작성하는지 비교합니다.
물론 중요한 문제입니다.
하지만 같은 AI 모델이라도 프로젝트에 대한 이해와 작업 원칙이 얼마나 명확하게 제공되느냐에 따라 결과는 크게 달라질 수 있습니다.
아무런 지침 없이 작업하는 AI와
프로젝트의 아키텍처, 의존성 정책, 보안 원칙, 변경 절차를 이해한 상태에서 작업하는 AI는
사실상 서로 다른 개발 환경에서 일하는 셈입니다.
여기서 AGENTS.md의 진정한 가치가 드러납니다.
AI의 코딩 능력을 높이는 것이 아니라, 그 능력이 프로젝트의 올바른 방향으로 사용되도록 만드는 것.
저는 이것이 AI 기반 개발에서 상당히 중요한 차이라고 생각합니다.

프로젝트 설계의 최선봉에 AGENTS.md가 있어야 하지 않을까 ?
조금 더 나아가 생각해 봅니다.
새로운 프로젝트를 시작할 때
우리는 보통 사용할 언어와 프레임워크를 결정하고, 데이터베이스 구조와 디렉터리 구성, 핵심 기능을 설계합니다.
그런데 AI와 함께 개발하는 환경이라면 순서를 조금 바꿔볼 필요가 있지 않을까요?
코드를 작성하기 전에 먼저 프로젝트가 지향하는 원칙을 정의하고, AI가 그 원칙을 이해하고 준수하도록 만드는 것입니다.
- 이 프로젝트는 어떤 철학으로 설계되는가?
- 코어와 확장 기능의 경계는 어디인가?
- 어떤 변경은 허용되고 어떤 변경은 금지되는가?
- 기존 구조와 새로운 요구사항이 충돌하면 무엇을 우선하는가?
- 테스트와 검증은 어떤 기준으로 수행하는가?
- AI는 어떤 작업을 자율적으로 수행하고 어떤 작업에서 승인을 받아야 하는가?
이런 질문에 대한 답이 정리되는 AGENTS.md는 단순한 개발 보조 문서가 아니라 프로젝트 설계의 출발점이 되야 합니다.
물론 AGENTS.md 하나가 모든 설계 문서를 대체할 수는 없습니다.
상세한 아키텍처 문서와 기술 명세, 테스트 정책은 여전히 필요합니다.
다만 AGENTS.md는 그러한 문서와 원칙을 AI의 실제 작업 과정에 연결하는 첫 번째 관문이라는 것입니다.
설계 문서가 프로젝트의 구조를 설명한다면, AGENTS.md는 AI가 그 구조를 존중하며 일하도록 만드는 기준점이라고 할까요.

잘 작성하는 것만큼 지속적으로 관리하는 것도 중요하다
또 하나 생각할 부분은 AGENTS.md가 한 번 작성하고 끝내는 문서가 아니라는 것입니다.
프로젝트는 계속 변화합니다.
새로운 기능이 추가되고, 기존 설계의 문제점이 발견되고, 더 나은 개발 원칙이 만들어집니다.
그런 변화가 코드에만 반영되고 AGENTS.md에는 반영되지 않는다면
AI는 어느 순간 과거의 원칙을 기준으로 현재의 프로젝트를 수정하게 될 수도 있습니다.
반대로 AGENTS.md에 너무 많은 내용을 무분별하게 넣는 것도 바람직하지 않을 것입니다.
중요한 원칙은 명확하게, 세부적인 내용은 적절한 문서로 분리하고, 실제 코드와 지침 사이에 모순이 발생하지 않도록 관리해야 합니다.
결국 AGENTS.md의 품질은 문서의 분량이 아니라
원칙의 명확성, 실제 구조와의 일치성, 지속적인 유지관리에 달려 있다고 생각합니다.
그리고 무엇보다 중요한 것은 AI가 지침을 언제나 완벽하게 지킬 것이라고 가정하지 않는 태도일 것입니다.
중요한 원칙은 테스트와 자동화된 검증, 코드 리뷰/분석 등도 뒷받침되어야 합니다.

결국 AI에게 코드를 맡기기 전에 우리가 해야 할 일
AI 코딩 도구가 발전할수록 개발자의 역할도 조금씩 달라지는 것 같습니다.
과거에는 어떻게 코드를 구현할 것인가가 중요한 고민이었다면,
이제는 AI가 어떤 구조와 원칙 안에서 코드를 구현하도록 할 것인가가 그에 못지않게 중요해졌습니다.
그리고 그 고민을 가장 먼저 구체화할 수 있는 곳이 AGENTS.md라고 생각합니다.
우리는 AI에게 더 좋은 프롬프트를 작성하는 방법을 고민합니다.
더 뛰어난 모델을 선택하고, 더 많은 작업을 자동화하려고 노력합니다.
하지만 정작 그 AI가 일하게 될 프로젝트의 헌장이라고 할 만한 문서를 얼마나 진지하게 작성하고 있을까요?
어쩌면 AI 기반 프로젝트의 완성도를 결정하는 첫 번째 코드는
PHP도, Python도, JavaScript도 아닌 AGENTS.md에 기록된 몇 줄의 설계 원칙일 것립니다.
물론 이것이 모든 프로젝트에 적용되는 절대적인 정답은 아닐 것입니다.
다만 AI와 함께 프로젝트를 설계하고 개발하는 시간이 늘어날수록 한 가지 생각은 점점 분명해집니다.
AI 도구에 무엇을 만들 것인지 알리는 지문보다, 어떤 원칙으로 만들어야 하는지를 규제하는 지문이 중요하다.
그런 의미에서 저는 AGENTS.md가 단순한 보조 파일을 넘어, AI 시대 프로젝트 설계의 최선봉에 놓일 만한 문서라고 생각합니다.

여러분은 AI 코딩 도구를 사용하면서 AGENTS.md를 얼마나 중요하게 다루고 계신가요?

그리고 새로운 프로젝트를 시작한다면, 첫 번째로 작성해야 할 파일은 무엇이라고 생각하시나요?

- 💫Glitter Gim