요약 (TL;DR)

AI 에이전트가 몇 개의 파일을 수정하고, 몇 개의 테스트를 실행한 뒤 "완료(Done)"라고 말할 때, 그것이 정말로 완료된 것일까요? 항상 그렇지는 않습니다. 예상치 못한 곳에서 여전히 문제가 발생할 수 있습니다.

저는 "완료(Done)"에 대한 엄격한 정의를 내리는 것을 선호하며, 이를 **태스크 완료 프로토콜 (Task Completion Protocol)**이라고 부릅니다. 이는 보통 AGENTS.md에 작성되며, 가장 단순한 형태는 다음과 같습니다:

• 저장소의 실제 린트 (lint) 및 테스트 명령어를 실행합니다.
• 실패한 부분을 수정하고 체크를 다시 실행합니다.
• 완료를 주장하기 전에 정확한 증거를 보고합니다.

이것이 CI(지속적 통합)나 코드 리뷰 (code review)를 대체하는 것은 아닙니다. 다만, 결함이 있는 상태가 다음 에이전트 세션, 풀 리퀘스트 (pull request), 또는 사용자에게 도달하기 전에 기본적인 검증 게이트를 앞당기는 역할을 합니다.

영상 가이드 (Video Walkthrough)

시각적인 설명을 선호하신다면, 이 영상에서 개념이 실제로 작동하는 모습을 확인할 수 있습니다. 저는 동일한 작업을 두 번 수행합니다. 완료 프로토콜이 없는 경우와 있는 경우를 비교하여, "완료"에 대한 명시적인 정의가 어떻게 도움이 되는지 보여줍니다. 또한 에이전트가 프로토콜을 따르도록 만드는 몇 가지 트릭과 기술도 소개합니다.

에이전트는 "완료"라고 말하지만, 저장소는 동의하지 않습니다.

아마도 다음과 같은 상황을 본 적이 있을 것입니다:

에이전트 (Agent):
완료되었습니다. 수정을 구현하고 테스트를 업데이트했습니다.

...

구현 자체는 올바르게 보일 수도 있습니다. 아마도 에이전트가 하나의 집중된 테스트를 실행하고, 디프 (diff)를 검토한 뒤 깔끔한 요약을 생성했을 것입니다. 하지만 저장소의 일반적인 체크를 실행하면 린트 (lint) 에러, 다른 곳에서 실패하는 테스트, 또는 에이전트가 잡아내지 못한 기타 오류를 발견하게 됩니다.

AI 보조 워크플로우 (AI-assisted workflows)가 여러 에이전트를 포함하는 방식으로 확장될수록 이 문제는 더 악화됩니다. 대화형 세션에서는 실패를 발견하고 직접 수정할 수 있습니다. 하지만 다단계 워크플로우 (multi-step workflow)에서는 한 작업자(worker)가 성공을 보고하면, 다음 작업자가 결함이 있는 상태에서 시작하게 됩니다. 이러한 문제들은 빠르게 누적되며, 최종 상태는 심각하게 망가질 수 있습니다.

저장소는 "완료"가 무엇을 의미하는지 정의해야 합니다

인간에게는 이것이 당연합니다. 몇 가지 변경 사항을 만들고, 테스트와 린트(lint)를 실행하고, 문제를 수정하고, 어쩌면 몇 가지 다른 사항들을 확인한 후에야 비로소 "완료"라고 말하는 것 말입니다. 에이전트에게는 이것이 문서로 작성되어 있어야 하며, AGENTS.md가 이를 위한 완벽한 장소입니다. 저는 이 섹션을 **작업 완료 프로토콜 (Task Completion Protocol)**이라고 부릅니다.

여러분의 저장소에 맞춰 조정할 수 있는 압축된 버전은 다음과 같습니다:

## 작업 완료 프로토콜 (Task Completion Protocol)

완료를 보고하기 전에, 작업을 코딩(coding) 또는 비코딩(non-coding)으로 분류하십시오.
...

저의 Go 백엔드 템플릿에는 이 프로토콜의 실제 버전이 포함되어 있습니다. 여기서는 make lint와 make test를 사용합니다. 여러분의 프로토콜에는 정확한 명령어와 중요한 특정 확인 사항들을 명시해야 합니다.

단순히 "테스트를 실행하세요"라고 말하지 마세요. 이는 여전히 에이전트가 추측하게 만듭니다. 에이전트가 실행해야 하는 정확한 명령어를 명시하는 것이 가장 좋습니다.

분류와 계층 구조의 중요성

"항상 모든 것을 실행하라"는 방식은 작은 저장소에서는 작동할 수 있습니다. 하지만 모노레포 (monorepo)에서는 비용이 빠르게 증가하며 때로는 터무니없는 일이 됩니다.

문서 변경 사항에는 전체 테스트 스위트 (test suite)가 필요하지 않습니다. CSS 변경 사항에는 백엔드 테스트 세트가 아니라 시각적 검증 (visual verification)이 필요할 수 있습니다. Terraform, Helm 및 유사한 도구들도 마찬가지입니다.

최소한 저는 작업을 코딩 또는 비코딩으로 분류합니다. 단순히 문서, 스킬 (skills) 또는 유사한 파일만 변경했다면 테스트를 실행하고 싶지 않기 때문입니다.

계층 구조 또한 합리적입니다. 각 영역은 자신만의 완료 프로토콜이 담긴 개별 AGENTS.md 파일을 가질 수 있습니다. 변경 유형마다 서로 다른 확인 사항과 명령어가 필요할 수 있기 때문입니다.

루트(root) AGENTS.md는 관련이 있는 경우 프로젝트 전반의 동작을 정의할 수 있습니다. 더 구체적인 파일들은 해당 위치에서 완료가 무엇을 의미하는지 정의할 수 있습니다. 일반적으로 저는 다음과 같은 구조를 사용합니다:

AGENTS.md
├── apps/web/AGENTS.md
├── apps/backend/AGENTS.md
...

그리고 저는 루트 AGENTS.md를 최소한의 내용으로 유지하려고 노력합니다.

보고(Reporting) 부분도 중요합니다

에이전트가 무엇을 보고할지 "추측"하게 두지 마세요. 명시적인 형식을 요구해야 합니다. 저는 보통 다음과 같은 형식을 사용합니다:

Lint: pass - make lint
Tests: pass - make test
Coverage: 87.42% - 이 부분이 매우 중요합니다
...

그리고 이것은 사실 당신이 읽기 위한 것이 아닙니다 (물론 저도 가끔 읽기는 하지만요). 이것은 에이전트를 위한 것입니다. 엄격한 보고 형식 (reporting format)은 에이전트가 실제로 당신의 체크 항목들을 실행하도록 더 많은 "동기"를 부여합니다. 그렇지 않으면 에이전트는 단순히 결과를 "추측"할 수도 있습니다.

동적인 부분도 중요합니다. 저는 보통 커버리지 (coverage) 보고를 요구합니다. 만약 커버리지를 수집하지 않고 있다면 (수집하시길 바랍니다), 테스트 소요 시간이나 에이전트가 추측할 수 없는 다른 무언가를 요구하세요. 저는 모델이 체크 항목을 실행하지 않고 이를 신뢰성 있게 보고하는 것을 본 적이 없습니다.

이것이 CI나 리뷰를 대체하지는 않습니다

완료 프로토콜 (completion protocol)은 로컬 행동 계약 (local behavioral contract)입니다. CI는 여전히 엄격하고 결정론적인 (deterministic) 관문으로 남아 있습니다.

당신은 여전히 파이프라인에서 결정론적인 체크를 원할 것이며, 변경 사항을 여전히 리뷰하고 검증해야 합니다. 테스트 통과가 요청된 동작이 올바르다거나, 아키텍처가 합리적이라거나, 리팩터링 (refactor) 과정에서 보안 모델이 유지되었다는 것을 증명하지는 않습니다. 하지만 이는 다음과 같은 견고한 기준선 (baseline)을 제공합니다:

• 저장소(repository)가 "그린 (green)" 상태임.
• 에이전트가 팀의 표준 체크 (canonical checks)를 사용함.
• 실패 사항이 다음 단계로 넘어가기 전에 더 빨리 포착됨.

하네스 (Harness)가 더 어렵게 만들 수도 있습니다

한 가지 좌절스러운 주의 사항은, 저장소 지침 (repository instructions)이 에이전트가 받는 항상 최우선 순위의 지침은 아니라는 점입니다. 하네스 (harness)는 명령 실행, 테스트 동작 및 최종 보고를 형성하는 제약 조건을 추가할 수 있습니다.

만약 에이전트가 명확한 완료 프로토콜을 반복적으로 무시한다면, AGENTS.md의 문구가 문제인 것이 아닐 수도 있습니다. 모델에게 어떤 지침이 검증 동작을 형성하고 있는지, 그리고 그 지침이 어디에서 왔는지 물어보세요. 저는 이런 종류의 조사를 위해 Agent Diagnostics Mode를 사용합니다.

작게 시작하세요

거대한 거버넌스 (governance) 문서가 필요하지는 않습니다. 책임감 있는 인간 기여자가 실행할 것으로 기대하는 체크 항목부터 시작하세요. 프로젝트가 성장함에 따라 완료 프로토콜을 확장해 나가면 됩니다.

이것은 저에게 큰 도움이 되었으며, 여러분에게도 도움이 되기를 바랍니다!