왜 이런 생각을 하게 됐을까?
요즘은 AI로 코드를 짜는 게 너무 자연스러워졌습니다. Codex, Claude Code, Gemini CLI 같은 도구들을 번갈아 쓰다 보니 “이제는 모델이 알아서 잘 해주지 않을까”라는 기대도 생겼습니다. 그런데 프로젝트를 몇 번 새로 시작하다 보니, 막연한 기대와는 다르게 초반에 아무 기준 없이 시작하는 게 오히려 더 위험하겠다는 느낌이 들었습니다.
처음 계기는 context7 같은 문서 조회 MCP였습니다. 모델 성능이 많이 좋아졌다고 해도, 최신 라이브러리나 버전 민감한 API에서는 여전히 공식 문서가 중요합니다. 문제는 이걸 언제 써야 하는지 매번 사람이 판단해야 한다는 점이었고, 그러다 보니 “이걸 규칙으로 만들 수 없을까?”라는 생각으로 이어졌습니다.
그 과정에서 AGENTS.md를 다시 보게 됐습니다. 예전에는 AGENTS.md를 프로젝트 설명 정도로만 써두곤 했는데, 그렇게 두고 개발을 시작하면 AI가 너무 자유롭게 움직일 가능성이 있어 보였습니다. 설계 결정을 어디까지 해도 되는지, 테스트 없이 구현을 끝내도 되는지, 이런 기준이 전혀 없는 상태였기 때문입니다. 사람에게도 규칙 없이 일을 맡기면 각자 다른 방향으로 가듯, AI도 크게 다르지 않을 것 같았습니다.
그래서 접근을 바꿔서 정리해보기로 했습니다. AGENTS.md를 설명 문서가 아니라 행동 규칙 파일로 쓰자는 쪽으로 생각을 정리했습니다. 무엇을 만들지는 SPECS로, 왜 그런 결정을 했는지는 ADR로 분리하고, AGENTS.md에는 “AI가 어떻게 행동해야 하는지”만 남기는 구조입니다. 이 구조가 맞다면, AGENTS.md가 커지는 시점 자체가 문서 분리 시점의 신호가 될 것 같다는 생각도 들었습니다.
여기까지는 아직 실험 단계지만, 대화를 통해 정리해보면서 몇 가지 규칙은 꽤 그럴듯해 보였습니다. 예를 들면 문서가 필요한 상황에서는 반드시 공식 문서를 보게 만들기, 트레이드오프가 있는 설계 변경은 ADR 없이는 진행하지 않기, 구현 작업이 끝나면 PR 초안이 필요한지 사용자에게 물어보게 하기 같은 규칙들입니다. 이런 규칙들이 있다면, AI가 무작정 구현부터 들어가는 상황을 줄일 수 있지 않을까 기대하고 있습니다.
Plan Then Act도 다시 보게 됐습니다. 단순히 계획을 세우고 구현하는 흐름보다, 아예 TDD의 Red, Green, Blue 순서를 명시적으로 넣는 편이 낫겠다는 생각이 들었습니다. 테스트를 항상 쓸 수는 없겠지만, 최소한 실패하는 테스트나 재현 절차를 먼저 정의하게 만드는 것만으로도 작업 흐름이 달라질 가능성이 있어 보였습니다.
문서 관리 측면에서도 정리가 됐습니다. AGENTS.md에 모든 걸 넣으려 하면 결국 유지가 안 될 테고, 규칙은 AGENTS.md에, 결정은 ADR로, 요구사항은 SPECS로 나누는 편이 훨씬 안정적일 것 같습니다. 이 구조라면 사용하는 AI 도구가 바뀌어도 큰 영향을 받지 않을 것 같고요.
아직 실제 프로젝트에서 충분히 검증했다고 말하긴 이르지만, 이번 정리를 통해 AI 코딩에서 중요한 건 코드보다 먼저 기준을 정리하는 일일지도 모르겠다는 생각은 확실히 들었습니다. 그래서 최소한의 AGENTS.md 템플릿을 만들어두고, 새 프로젝트를 시작할 때마다 이 기준 위에서 출발해보려고 합니다.
AI 덕분에 구현 속도는 분명히 빨라졌습니다. 다만 그만큼, 어디까지 맡기고 어디서 멈추게 할지를 정하는 문서의 중요성도 같이 커진 것 같다는 기대를 하게 됩니다. 이 템플릿이 실제로 얼마나 효과가 있을지는… 나중에 확인해보겠습니다 🤩
GITHUB ⭐ 추가 감사합니다~
GPT5.2와 함께 고민하고 작성 했습니다.