AI Agent에게 일하기 좋은 환경 만들기

Intro: AI에게 큰 프로젝트를 맡겨보기로 했다

꽤 큰 규모의 신규 프로젝트를 시작하게 되었다. 이번 프로젝트에는 AI 를 조금 더 제대로 활용해봐야겠다 생각했다.

그동안은 AI를 잘 활용하는 방법 자체에 집중하기 보다는, DDD와 헥사고날 아키텍처, 백엔드 전반적인 개념을 이해하고 직접 설계와 코드에 개입하는 것이 좋다고 생각했다. 아직 완전히 숙지하지 못한 개념을 AI 에게 맡겨버리게 되면, 결과물은 빠르게 나오더라도 내가 왜 이런 구조를 선택했는지 제대로 이해하지 못하고 넘어가게 될거라고 생각했다.

여러 작업을 거치면서 이제는 팀 내에서 사용하는 아키텍처와 개발 방식에 적응이 되어서, 규모가 있는 프로젝트를 AI 와 함께 진행하며 AI 를 최대한 활용해보려고 한다. 큰 프로젝트를 AI 에게 맡기면 AI 를 사용하는 방법을 빠르게 익힐 수 있다고 생각했기 때문이다.

같은 모델, 다른 Harness, 다른 결과물

요즘 AI Agent 를 활용하면서 개발자들 사이에서 가장 화두가 되는 주제가 Harness 인것 같다. 그전까지는 모델의 종류나, 성능을 비교하고 새로운 모델이 나올 때 마다 사람들이 열광했던것 같다. 이제는 같은 모델을 사용하더라도 어떤 context 와 Harness 를 붙이는지에 따라서 결과물이 달라진다는 것에 관심이 쏠리고 있다. 최근 논문도 이런 Harness Engineering 트렌드를 뒷받침한다. - ‘Same Model, Different Harness: Different Coding-Agent Results’ 에서도 Harness 에 대한 실험을 하고 있다. 논문에서는, 모델 별로 별도의 튜닝이나 학습을 하지 않고, Harness 의 운영 방식을 다르게 하여 실험한다. 실험의 대조군(Control Harness)은 기본 설정을 적용하고, 실험군 (Treatment Harness) 에는 context 관리, stall 대응을 하도록 설계 한다. 여기에서 context 란, AI Agent 가 업무를 수행하는데 참고하는 내용을 의미하며, stall 은 Agent 가 작업을 제대로 진전시키지 못하고, 같은 행동을 반복하거나 막혀있는 상태를 의미한다. 실험에서 사용한 "Yuj" 라는 Harness 는 모델이 작업한 전체 기록은 보존하지만, 모델에게는 작업에 필요한 것만 골라서 보여준다. 

위의 그림은 기본 하네스 구조이며, 모델의 작업이 반복해서 진행되면서 context 가 가득 차게 되면 실행이 종료된다. 여기에서 context가 가득찬다는 의미는 정해져 있는 token 한도를 모두 다 사용해버렸다는 의미이다. 

반면 실험군 Harness의 경우에는, Context 가 완전히 꽉 차기 이전에 일정 사용량을 기준으로 Harness가 직접 개입해서 오래된 결과를 압축한다. 또는 모델이 작업에서 같은 실패를 반복적으로 겪게 되는 경우 다시 반복하지 말고, 다른 접근 방식으로 task 를 해결하도록 개입한다. 실제로 "Yuj" 의 repository 를 보면 아래와 같은 지시문을 코드에서 확인할 수 있었다. 

_UT_SUGGESTION = {
    "reread_slump": (
        "stop re-reading and re-verifying things you have already confirmed; "
        "make your next action a source edit or a test run"
    ),
    "repeat_wall": (...),
}

정리하자면, Harness 는 Agent의 문제 해결을 대신하는 것이 아니라, 실행 경로가 정체되었을 때 결정적인 규칙으로 방향을 교정하는 역할을 한다. 이미 예측 했겠지만, 논문에서 실험의 결과는 context window를 20K token으로 제한한 환경에서 기존의 harness는 169개 문제 중 43개를 해결했지만, context 관리와 stall detection을 적용한 harness는 72개 문제를 완전히 해결했다. 같은 모델 일 때, 더 결정적인(deterministic) 규칙을 씌우는 harness가 더 좋은 성과를 낸 것이다.

Agent Environment - Agent 가 일하기 좋은 환경

사실 우리가 사용하는 Claude Code 에는 이미 Anthropic 이 만들어 놓은 Harness 가 적용되어 있다. 그렇지만, 이미 harness가 적용되어 있다고 하더라도 각자 팀에서 지향하는 코드 규칙, 아키텍처, 도메인 지식을 따로 주입해주어야 더 퀄리티 높은 결과물을 만들 수 있다. 이런 고민은 우리 팀 (혹은 이 글을 읽는 당신의 팀) 뿐만 아니라, OpenAI 에서도 동일하게 하고 있었다. OpenAI 팀은 5개월동안 사람이 수작업으로 쓴 코드를 작성하지 않고, 제품을 구축하고 출시하는 실험을 이 글에서 소개한다.  

https://openai.com/ko-KR/index/harness-engineering/

하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기

초기 진행은 더뎠는데, 그 이유는 모델의 역량 때문이 아니라 모델이 일할 수 있는 환경이 제대로 갖추어 지지 않았기 때문이라고 한다. 에이전트가 목표를 달성하기 위한 도구, 내부 구조 등이 부족했다. 이 중에서 흥미롭게 읽었던 부분은 AGENTS.md 파일의 컨텍스트를 장황한 백과사전 처럼 제공했던 때 보다, 목차를 제공하는 것이 효과적이었다는 점이다. 실제로 아래와 같은 목차를 사용했을 때 에이전트가 어떤 context를 볼지 직접 추론할 때 용이했으며, context가 너무 많으면 에이전트는 의도적으로 탐색하기 보다 패턴 매칭을 수행하게 된다고 한다. 

AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│   ├── index.md
│   ├── core-beliefs.md
│   └── ...
├── exec-plans/
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md
├── product-specs/
│   ├── index.md
│   ├── new-user-onboarding.md
│   └── ...
├── references/
│   ├── design-system-reference-llms.txt
│   ├── nixpacks-llms.txt
│   ├── uv-llms.txt
│   └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md

실무에서도 이 글의 방향과 비슷하게, 도메인 규칙을 담은 하나의 거대한 백과사전 용도의 Repository 를 요즘 작성하고 있다. 그리고 코드와 Repository의 내용이 일치하지 않으면 최신화를 하여 Repository 를 업데이트해주고 있다. 이런 skill을 따로 만들어서 사용중이다. OpenAI 의 글에서도 이를 "doc-gardening" 이라고 하며, 더 이상 유효하지 않은 문서화를 검토하여 수정용 pull request를 열도록 자동화 했다고 한다. 

Ticket Development Workflow

최근 목표로 하는 것은 티켓을 하나 주면 AI Agent 들이 직접 계획, 개발, 테스트, QA 를 하도록 하나의 워크플로우로 만들어 내려고 하고 있다. 코드를 작성한 Agent와 동일한 Agent 에게 리뷰를 하도록 하면 틀린 점을 찾아내기 어려워 하는 반면, 다른 Agent 를 통해 코드 리뷰를 하면 더 성능이 좋다는 것을 알게 되었다. 그래서 Agent 를 기능별로 여러 개 두고, Harness 를 촘촘하게 작성했다.

Ticket
  ↓
Requirements / Context
  ↓
Planning
  ↓
Implementation
  ↓
Test
  ↓
Code Review
  ↓
Fix
  ↓
PR

처음에는 이 구조를 더 촘촘하게 만들수록 결과도 좋아질 것이라고 생각했다. 필요한 지식을 제공하고, 역할별 Subagent를 만들었다. 그런데 실제로 Workflow를 반복해서 사용하면서 예상하지 못한 문제가 먼저 나타났다. 체감되는 품질 향상에 비해 Token 사용량이 지나치게 커졌다. 실행 과정을 살펴보니 일부 Workflow에서는 Agent가 다시 Subagent를 호출하고, 그 Subagent가 또 다른 Agent를 호출하면서 작업이 중첩되고 있었다. 비슷한 역할의 Rules와 Workflow가 동시에 실행되는 경우도 있었다. 사용량 리포트를 확인해보니 최근 7일간 56%의 usage가 subagent-heavy session에서 발생했고, 44%는 150K가 넘는 context를 사용한 session에서 발생했다. 

아래의 모양처럼 sub agent 가 agent 를 만들어내는 중첩 구조로 파악 되었다. 

Ticket Development
      ↓
Workflow Agent
      ↓
Subagent
   ↙       ↘
Agent     Agent
  ↓         ↓
Skill     Tool
...

아직 어떤 구성으로 workflow 를 만들어야 가장 효과적인지 답을 찾아나가는 중이다. 앞으로는 지금까지 추가한 Rules, Skills, Subagents와 Workflow를 하나씩 걷어내면서 실제로 품질에 기여하는 요소가 무엇인지 확인해보려고 한다. 

 

Outro: AI를 잘 쓰는 것은 Context와 Workflow를 설계하는 일 

코드는 이제 개발자보다 AI 가 더 잘 작성하고, 개발자는 "AI를 잘 쓰는 것" 이 중요하다고들 이미 인식하고 있다. 그리고 AI 를 잘 쓴다는 것은 결국 AI 가 일하기 좋은 환경을 개발자가 만들어주는 일이 된다. Context 를 얼마 만큼 어느 시점에 보여줄지 결정적으로 일하는 방식을 만들어 나가는 것이 중요해졌다. 그리고 더 나아가서 AI 가 일하는 방식을 하나의 Workflow 묶음으로, 최대한 인간의 개입없이 자동화 한다면 일을 더 빠르게 진행할 수 있을 것이라고 생각한다. 한편으로는 이 Workflow 를 구성해둔 이후 개발자의 역할은 무엇이 될까 ? 라는 생각도 든다.