서론 - AI 시대의 개발 용어에 대한 개인적인 정리

이번 글은 AI 시대의 개발 용어를 내 관점에서 정리하기 위해 썼다. 업계에서 자주 보이는 표현, 선배 개발자들의 아이디어, 그리고 내가 AI와 함께 코드를 작성하며 겪은 시행착오를 함께 묶어보려 한다. 핵심 키워드는 Architecture, Guidance, Rules다. LLM Agent와 함께 코드를 구성하는 시대에는 이 세 가지가 이전보다 더 중요해졌다. 한편, 이러한 도구들의 성능이 강력해질수록 개발자의 기본기는 더 선명하게 드러난다.

AI와 페어 프로그래밍을 하다 보면 이런 질문을 하게 된다. 왜 기존 패턴과 다른 코드를 쓰는가. 왜 내가 지시한 대로 움직이지 않는가. 왜 의도하지 않은 구조로 구현하는가. 이 질문들은 궁극적으로는 개발자의 '의도'가 AI에게 온전히 전달되지 않거나, 전달되더라도 그 결과가 정합적으로 출력되지 않는 경우에 발생한다. 이 문제를 줄이기 위해 AI Harness, LLM Memory, AGENTS.md 같은 장치가 등장했다. 실제로 많은 불편함이 줄어들었지만, 내가 이 글에서 집중하고 싶은 것은 더 구체적인 원칙이다.

나는 그 원칙을 Architecture, Guidance, Rules로 정리하고 싶다. 이번 글은 그중 Architecture와 Harness의 관계를 먼저 다룬다. 다음 글에서는 Guidance와 route 문서로 논의를 이어갈 예정이다.

1. AI Harness란 무엇인가

AI Harness라는 말은 맥락에 따라 다르게 쓰인다. 때로는 가드레일을 뜻하고, 때로는 평가 시스템을 뜻하며, 때로는 Agent가 안정적으로 일하기 위한 개발 인프라 전체를 가리킨다. 이 글에서는 AI Harness를 Agent가 따라야 하는 인프라로 본다. 그보다 더 구체적으로는 AI가 개발자의 의도를 안정적으로 구현하도록 돕는 인프라 시스템이라고 정리해보려 한다.

Anthropic의 Harness 관련 아티클에서도 볼 수 있듯, 모델의 추론 능력을 더 안정적으로 쓰기 위한 노력은 handoff 문서, 평가자, 작업 흐름, 실행 환경 같은 장치로 이어진다. 이 관점에서 보면 Harness는 단순한 도구의 묶음에서 벗어나, Agent가 어떤 정보를 보고, 어떤 순서로 판단하며, 어떤 기준으로 결과를 검증해야 하는지를 정리한 작업 시스템으로서 작용한다. 또한, 이러한 시스템은 코드베이스와 함께 개발자의 경험이 쌓이면서 더 넓어지고 깊어진다. 특정 기능을 구현하며 발견한 규칙을 AGENTS.md에 기록해두면, 그 문서도 다음 작업에서 Harness처럼 동작하는 것처럼. 그래서 표현에 너무 매달릴 필요는 없다고 생각한다. 내가 의도한 것을 더 안정적으로 구현하도록 돕는 인프라라면, 그것을 넓은 의미의 Harness로 볼 수 있을 것이다.

2. Architecture는 왜 Harness의 일부인가

그렇다면 Architecture는 Harness와 어떤 관계에 있을까. 위에서 언급했듯, AI가 내 의도를 올바르게 반영하고 안정적으로 동작하도록 돕기 때문에, Architecture 역시 넓은 의미의 Harness에 포함된다. 코드베이스를 구성하는 아키텍처는 Agent가 코드를 이해하고 변경하는 방식에 직접적인 영향을 준다. 어떤 코드와 모듈을 어디에 두고, 어떤 방향으로 의존성을 흐르게 하며, 어떤 책임을 어디에 배치할지를 정하는 청사진이다. 이 청사진의 흐름이 곧 개발자 의도의 흐름이다. 따라서 좋은 구조에는 서비스의 의도가 담긴다. 예를 들어 Clean Architecture로 구성된 코드베이스에서는 Domain Layer를 먼저 보면 서비스가 어떤 비즈니스 규칙을 중심에 두는지 비교적 쉽게 파악할 수 있다. 이 구조가 잘 유지되면 개발자 사이의 소통 비용이 줄어든다. 새로운 코드를 추가할 때도 기존 컨벤션을 따라 변경 범위를 좁힐 수 있다. 의도가 구조로 전달되기 때문이다.

이 조건은 사람에게만 적용되지 않는다. Agent도 같은 코드베이스를 읽고 판단한다. 구조가 흐트러지면 Agent는 잘못된 위치에 코드를 추가하거나, 기존 패턴과 어긋난 구현을 선택하기 쉽다. 그렇기 때문에, Matt Pocock은 AI Engineer 채널의 워크숍에서 좋은 구조가 좋은 출력을 만든다고 강조한다. Architecture가 Agent를 위한 Harness로서 올바르게 동작하려면, 개발자는 좋은 구조를 지향해야 한다.

3. Architecture 관리는 왜 별도로 필요한가

하지만 Architecture를 Harness 안에 포함할 수 있다고 해서, Harness가 Architecture를 대체할 수 있는 것은 아니다. 두 개념은 바라보는 중심이 다르다. Harness의 중심은 Agent다. Agent가 어떻게 동작해야 하는지, 어떤 출력을 만들어야 하는지, 어떤 행동을 피해야 하는지를 정리한다. 반면 Architecture의 중심은 서비스다. Agent를 도구로 사용하는 것은 부수적이다. 우리 개발자의 궁극적인 목적은 서비스의 유지보수와 개발이다. 상황, 정책, 비용, 팀의 역량에 따라 아키텍처는 유연하게 대응할 수 있어야 하기 때문에 서비스의 의도를 보존하는 일은 매우 중요하다. 이러한 관점에서, Harness는 그 자체로 좋은 도구로 쓸 수 있으나 개발자가 AI와 페어 프로그래밍 할 때 발생하는 모든 문제를 해결할 수 있는 silver bullet은 될 수 없다.

내가 강조하고자 싶은 것은 Architecture를 의도의 추상으로 이해하는 것이다. 아키텍처는 개발자의 의도와 서비스의 방향을 압축해서 보여준다. 이 추상이 흔들리면 Agent에게 아무리 많은 규칙을 줘도 결과가 불안정해진다. 따라서 AI와 협업할 때는 Architecture 자체를 관리해야 한다. 그리고 그 Architecture를 어떻게 읽고 따라야 하는지 Guidance로 제공해야 한다.

결론 - 좋은 Guidance에 대한 질문

이번 글에서는 내가 혼동했던 용어들을 간단히 정리했다. AI Harness는 의도된 동작을 안정적으로 출력하도록 돕는 인프라 시스템으로 이해할 수 있다. 또한 Architecture는 단순한 코드 배치가 아니라 의도의 구조화라는 점을 짚었다. 좋은 구조는 사람에게도, Agent에게도 변경의 방향을 알려주는 기준이 된다.

다만 Harness와 Architecture는 서로 다른 계층을 본다. Harness는 Agent의 행동을 다루고, Architecture는 서비스의 의도를 다룬다. AI 시대에서 높은 효율을 내고자 한다면 둘 중 하나만으로는 충분하지 않다. 다음 글에서는 이 둘을 연결하는 Guidance를 다룰 예정이다. 특히 Agent가 코드베이스를 어떤 경로로 읽고, 어떤 규칙을 우선해야 하는지 정리하는 route 문서와 Guidance 문서에 대해 이야기해보려 한다.

참고 자료

https://www.youtube.com/watch?v=-QFHIoCo-Ko&t=3939s
https://www.anthropic.com/engineering/harness-design-long-running-apps