AGENTS.md는 문서가 아니라 운영 코드다

Agentic AI가 등장한 뒤, 개발의 문턱이 낮아졌다는 말이 자주 나온다. 실제로 겉으로는 그렇게 보인다. 예전보다 적은 코드로도 결과를 만들 수 있고, 비개발자도 어느 정도는 프로토타입을 직접 조립할 수 있게 됐다. 하지만 여기서 곧바로 “개발이 쉬워졌다”라고 결론 내리는 건 순진한 착각이다. 문턱이 사라진 것이 아니라, 문턱의 위치가 바뀌었기 때문이다.

과거에는 구현 능력 자체가 가장 큰 병목이었다. 이제는 구현 일부를 모델이 대신할 수 있다. 대신 다른 병목이 더 크게 드러난다. 무엇을 맡기고, 어떤 맥락을 주고, 어떤 제약을 걸고, 어디까지를 모델의 자율성으로 둘지를 설계하는 문제가 훨씬 중요해졌다. 즉 Agentic AI는 개발을 쉽게 만든 것이 아니라, 개발자의 통제 지점을 바꿨다. 구현 난이도의 일부는 낮아졌지만, 지시 난이도와 운영 난이도는 오히려 더 높아졌다고 보는 편이 정확하다.

이 변화의 핵심에는 제한된 컨텍스트 윈도우가 있다. 모델은 아무리 똑똑해 보여도 주어진 맥락 안에서만 판단한다. 필요한 정보가 빠져 있으면 자신감 있게 틀리고, 불필요한 정보가 많으면 중요한 제약을 놓친다. 결국 정확한 답변과 안정적인 결과를 얻으려면 컨텍스트의 품질과 토큰 제어가 결정적이다. 어떤 정보를 앞에 두고, 무엇을 생략하고, 어떤 순서로 배치할지에 따라 결과의 수준이 크게 달라진다. Agentic AI를 잘 쓴다는 것은 좋은 질문을 하는 것만이 아니라, 좋은 실행 문맥을 설계하는 일에 가깝다.

그래서 프롬프트 엔지니어링, 컨텍스트 엔지니어링, 하네스 엔지니어링이라는 말이 자연스럽게 등장했다. skills, MCP, agent 구성에 대한 공유가 활발한 것도 같은 맥락이다. 어떤 도구를 연결할지, 어떤 역할 분리를 할지, 어떤 제약을 시스템적으로 강제할지에 대한 논의는 점점 더 실무적이 되고 있다. 이 흐름은 필요하다. 하지만 나는 여기서 한 걸음 더 들어가야 한다고 생각한다. 결국 전역 환경과 현재 프로젝트를 함께 설명하는 AGENTS.md 같은 문서가 운영의 중심에 놓여야 한다.

왜 하필 AGENTS.md일까. 단순한 프롬프트 한 덩어리나 README만으로는 부족하기 때문이다. 모델은 매번 프로젝트의 우선순위, 금지사항, 작업 습관, 도구 사용 원칙을 새로 추측하려 든다. 그 추측은 자주 틀린다. AGENTS.md는 이런 추측 비용을 줄이는 장치다. 전역적인 작업 원칙과 프로젝트 특화 규칙이 만나는 지점이며, 반복적으로 설명해야 할 실행 규약을 축적하는 인터페이스다. 다시 말해 사람의 습관, 프로젝트의 제약, 모델의 한계를 함께 문서화하는 운영 계층에 가깝다.

중요한 점은 이 문서를 한 번 잘 써두는 것으로 끝낼 수 없다는 것이다. AGENTS.md는 정적인 안내문이 아니라 계속 수정해야 하는 운영 코드다. 프로젝트가 바뀌면 필요한 맥락이 바뀌고, 모델이 바뀌면 반응 방식이 달라지고, 사용자의 습관이 바뀌면 지시 체계도 달라진다. 처음에는 잘 먹히던 규칙이 어느 순간부터는 오히려 성능을 떨어뜨릴 수도 있다. 그래서 강한 규칙을 많이 적는 것만으로는 충분하지 않다. 규칙은 필요하지만, 완성본이 아니라 관찰 결과에 따라 계속 보정해야 하는 초안에 가깝다.

여기서 놓치기 쉬운 점이 하나 더 있다. AGENTS.md는 모델을 위한 문서이면서 동시에 사용자를 교정하는 문서이기도 하다. 사람도 늘 같은 방식으로 지시하지 못한다. 어떤 날은 세밀하게 설명하고, 어떤 날은 생략하고, 어떤 날은 본인이 중요하게 생각하는 제약조차 빠뜨린다. 결국 문제가 반복되면 모델만 탓할 일이 아니라, 사용자의 작업 습관과 지시 방식도 함께 표준화해야 한다. 그런 점에서 AGENTS.md는 모델을 통제하는 장치이면서, 사용자 자신을 통제하는 장치이기도 하다.

그래서 나는 AGENTS.md를 설정 파일처럼 보지 않는다. 오히려 머신마다, 환경마다, 사용자마다 다르게 컴파일해야 하는 소스코드에 가깝다고 생각한다. 같은 철학을 담고 있어도 어떤 모델을 쓰는지, 어떤 IDE와 도구 체인을 붙였는지, 어떤 프로젝트 구조를 갖고 있는지에 따라 최적의 형태는 달라진다. 그래서 다른 사람이 잘 써둔 AGENTS.md를 그대로 복붙하는 방식은 오래가지 못한다. 중요한 것은 좋은 문서를 가져오는 일이 아니라, 지금 내 환경에서 잘 작동하도록 계속 컴파일하고 다시 빌드하는 일이다.

Agentic AI 시대의 생산성은 모델의 지능만으로 결정되지 않는다. 더 정확히는, 모델이 일할 문맥을 얼마나 잘 설계하고 유지하느냐에 더 크게 좌우된다. 그 문맥 설계의 중심에는 결국 계속 손봐야 하는 AGENTS.md가 있다. 문서처럼 보이지만 실제로는 운영 코드에 더 가깝다. 그리고 운영 코드는 언제나, 현실에 맞게 계속 수정되어야 한다.