AI 에이전트가 코드를 얼마나 잘 쓰는지보다 더 급한 질문이 생겼습니다. "그 에이전트가 쓴 코드를 조직이 믿고 계속 운영할 수 있는가?"입니다.
최근 공개된 여러 사례는 이 질문이 더 이상 이론이 아님을 보여줍니다. OpenAI는 Codex 에이전트를 활용해 사람이 직접 코드를 작성하지 않는 조건으로 100만 라인 이상 규모의 내부 프로덕션 애플리케이션을 구축했다고 설명했습니다.1 중요한 지점은 "모델이 똑똑해졌다"가 아닙니다. 코드 생성이 빨라질수록 검증, 제약, 회수 장치가 병목이 된다는 점입니다.
하네스 엔지니어링은 '더 좋은 지시문'이 아니다
하네스 엔지니어링은 AI 에이전트 주변에 제약, 도구, 문서, 검증 루프, 관측 체계를 설계하는 일입니다. 짧게 말하면 인간은 방향과 경계를 정하고, 에이전트는 그 안에서 실행합니다.
프롬프트 엔지니어링은 한 번의 요청을 잘 쓰는 기술에 가깝습니다. 컨텍스트 엔지니어링은 에이전트가 무엇을 보게 할지 조정합니다. 반면 하네스 엔지니어링은 에이전트가 어떤 환경에서 실행되고, 어디서 멈추며, 실패했을 때 어떻게 고치게 할지를 다룹니다.
이 차이는 실무에서 큽니다. "우리 팀 스타일을 지켜줘"라고 쓰는 것은 확률적 기대입니다. 반면 "이 import 경계를 어기면 CI에서 실패한다"는 결정적 제약입니다. AI 코드가 늘어날수록 팀의 품질은 프롬프트 문장력이 아니라 이런 강제 장치의 밀도에 좌우됩니다.
리포지터리는 에이전트의 기억 장치가 된다
에이전트에게 모든 정책 문서를 한 번에 넣는 방식은 오래가지 않습니다. 컨텍스트 창은 커졌지만 무한하지 않고, 긴 작업에서는 정보가 희석됩니다. 그래서 여러 도구와 팀은 리포지터리 안에 AGENTS.md, CLAUDE.md, 규칙 파일, 작업 상태 파일을 두는 방식을 채택하고 있습니다.
Codex 쪽 문서와 가이드들은 AGENTS.md를 저장소 루트에서 현재 디렉터리까지 계층적으로 읽는 구조로 설명합니다.2 실제 OpenAI Codex 저장소의 AGENTS.md에는 Rust 모듈 크기 제한, 특정 명령 사용법, 테스트 실행 방식, 건드리지 말아야 할 샌드박스 관련 코드 같은 구체 규칙이 들어 있습니다.3
여기서 핵심은 문서를 길게 쓰는 것이 아니라 "에이전트가 매번 다시 읽을 수 있는 작고 실행 가능한 지도"를 만드는 것입니다. 루트 파일은 10개 안팎의 핵심 규칙과 진입점을 담고, 세부 규칙은 하위 디렉터리 문서와 린터·테스트로 내려보내야 합니다. 문서가 설명서가 아니라 실행 환경의 일부가 되는 셈입니다.
좋은 가드레일은 에이전트가 스스로 고치게 만든다
하네스의 품질은 실패 메시지에서 드러납니다. "lint failed"는 사람에게도 불친절하고 에이전트에게도 불친절합니다. 반대로 "console.log 대신 logger.info({event, ...data}) 형식을 사용하라"처럼 수정 방향을 포함한 오류 메시지는 곧 에이전트의 다음 프롬프트가 됩니다.
이 방식은 에이전트를 믿는다는 뜻이 아닙니다. 오히려 반대입니다. 에이전트가 실수할 것을 전제로, 같은 실수가 반복되지 않도록 제약을 코드화하는 접근입니다. 공개 자료들은 이를 제약 하네스, 피드백 루프, 품질 게이트의 층으로 설명합니다.4
다만 가드레일은 많을수록 좋은 것이 아닙니다. 너무 낮은 복잡도 제한, 지나치게 세밀한 스타일 규칙, 예외 없는 의존성 금지는 정상적인 리팩터링까지 막을 수 있습니다. 시작점은 좁아야 합니다. 실제 장애나 반복 리뷰에서 나온 규칙부터 CI의 "경고"가 아니라 "실패"로 승격하고, 효과를 측정하며 넓히는 편이 안전합니다.
개발자의 일은 사라지지 않고, 통제면이 바뀐다
AI 코딩 도입의 역설은 이미 관찰되고 있습니다. 생성 속도는 올라가지만, 검토 부담과 불안정성도 함께 커질 수 있습니다. 한 분석은 AI 도입 증가가 소프트웨어 전달 처리량과 불안정성 모두의 증가와 관련된다고 정리했고, 또 다른 보안 분석은 AI 생성 코드 확산 이후 보안 발견 건수가 크게 늘었다고 보고했습니다.4
따라서 "AI가 코딩을 대신한다"는 표현은 절반만 맞습니다. 구현 일부는 에이전트가 맡을 수 있습니다. 하지만 아키텍처 경계, 테스트 전략, 승인 정책, 문서 신선도, 관측 가능성은 더 중요해집니다.
지금 팀이 점검해야 할 질문은 단순합니다.
에이전트가 반드시 읽는 저장소 내 지도가 있는가?
아키텍처 위반이 리뷰가 아니라 자동 검사에서 잡히는가?
실패 메시지가 에이전트가 고칠 수 있을 만큼 구체적인가?
오래된 문서와 실제 코드의 차이를 주기적으로 줄이는 절차가 있는가?
하네스 엔지니어링은 아직 완전히 굳어진 표준 직무명이라기보다, 여러 팀이 비슷한 문제를 풀며 붙이기 시작한 이름에 가깝습니다. 그러나 방향은 분명합니다. AI 에이전트를 도입하는 팀은 더 이상 "어떤 모델을 쓸까"에서 멈출 수 없습니다. 이제 경쟁력은 에이전트가 일할 수 있는 안전한 작업장, 즉 하네스를 얼마나 잘 설계하느냐에서 갈립니다.
참고
1Harness Engineering for AI Coding Agents: Constraints That Ship Reliable Code
2OpenAI Codex Setup: AGENTS.md, MCPs, Skills (Definitive Guide 2026)
3codex/AGENTS.md at main · openai/codex · GitHub
4Harness Engineering for AI Coding Agents: Constraints That Ship Reliable Code
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.