코딩 에이전트(Coding agents)가 탈선하는 이유는 보통 능력이 부족해서가 아닙니다. 작업 내용이 해석의 여지를 너무 많이 남겨두기 때문에 탈선하는 것입니다.

"인증(authentication) 부분을 정리해줘"와 같은 요청은 이미 코드베이스를 알고 있는 사람에게는 명확하게 들립니다. 하지만 에이전트에게는 헬퍼 함수 하나를 이름을 바꾸는 것부터 인증 스택 전체를 교체하는 것까지 무엇이든 의미할 수 있습니다.

해결책은 더 긴 프롬프트(prompt)를 작성하는 것이 아닙니다. **네 가지 명시적인 부분으로 구성된 브리프(brief)**를 작성하는 것입니다:

1. 결과 (Outcome)
2. 컨텍스트 (Context)
3. 가드레일 (Guardrails)
4. 완료 정의 (Definition of Done)

아래는 제가 사용하는 정확한 구조입니다.

1. 결과를 관찰 가능한 변화로 기술하기

작업이 완료되었을 때 사용자나 시스템 측면에서 무엇이 달라져야 하는지를 설명하세요.

미흡한 예:

로그인 버그를 수정해줘.

더 나은 예:

사용자가 만료된 매직 링크(magic link)를 제출하면, 기존의 "링크가 만료되었습니다" 메시지를 보여주고, 페이지를 벗어나지 않고 새 링크를 요청할 수 있는 버튼을 제공해줘.

더 나은 버전은 에이전트에게 목적지를 제공합니다. 구현 방법을 규정하지는 않지만, 성공 여부를 테스트할 수 있게 만듭니다.

2. 의사결정을 변화시키는 컨텍스트만 제공하기

컨텍스트(Context)는 모호함을 제거할 때 유용합니다. 전체 저장소(repository)를 구경시켜 주는 식이라면 소음(noise)이 됩니다.

유용한 컨텍스트에는 주로 다음이 포함됩니다:

• 관련 엔트리 포인트(entry point) 또는 라우트(route)
• 재사용해야 할 기존 컴포넌트(component) 또는 서비스(service)
• 코드베이스 내 다른 곳의 유사한 구현 사례
• 관련 테스트를 실행하는 데 사용되는 명령어
• 하위 호환성(backwards compatibility)과 같은 알려진 제약 사항

예시:

해당 페이지는 app/auth/verify/page.tsx에 구현되어 있습니다. lib/auth/client.ts에 있는 requestMagicLink()를 재사용하세요. 기존 에러 메시지 스타일은 components/auth/AuthNotice.tsx에 있습니다.

이 정도면 최종 패치(patch)를 이미 알고 있는 척하지 않고도 조사를 시작하기에 충분합니다.

3. 변경 범위를 정의하는 가드레일 추가하기

가드레일(Guardrails)은 작은 작업이 의도치 않은 재작성(rewrite)으로 이어지는 것을 방지합니다.

유용한 가드레일 세트는 다음과 같을 수 있습니다:

• 공용 API (public API)를 변경하지 마세요.
• 의존성 (dependencies)을 추가하지 마세요.
• 현재의 시각적 디자인 (visual design)을 유지하세요.
• 생성된 파일 (generated files)을 편집하지 마세요.
• 인증 흐름 (authentication flow)과 그 테스트로 변경 사항을 제한하세요.
• 데이터베이스 마이그레이션 (database migration)이 필요해 보인다면, 생성하기 전에 중단하고 그 이유를 설명하세요.

마지막 가드레일이 에이전트에게 에스컬레이션 규칙 (escalation rule)을 제공한다는 점에 주목하세요. "중단하고 설명하라"는 불확실한 가정이 마이그레이션으로 이어지게 두는 것보다 훨씬 안전합니다.

4. 완료 정의 (Definition of Done)를 증거 기반으로 만들기

"정상적으로 작동함"은 완료 정의 (Definition of Done)가 아닙니다. 직접 검사할 수 있는 증거를 요구하세요.

매직 링크 (magic-link) 예시의 경우:

• 만료된 링크가 기존의 에러 메시지를 표시함.
• "새 링크 요청"을 클릭하면 기존 클라이언트 메서드 (client method)가 한 번 호출됨.
• 성공 및 실패 상태가 모두 테스트에 의해 커버됨.
• 관련 테스트 스위트 (test suite)가 통과함.
• 최종 응답에 변경된 파일 목록과 실행된 검증 명령어가 포함됨.

이를 통해 작업의 종료를 작은 인수 테스트 (acceptance test)로 전환할 수 있습니다.

복사 가능한 작업 브리프 (task-brief) 템플릿

# 결과물 (Outcome)
[완료되었을 때 존재해야 하는 관찰 가능한 동작을 설명하세요.]

...

완전한 버그 수정 브리프 (bug-fix brief)

# 결과물 (Outcome)
만료된 매직 링크가 제출되었을 때, 기존의 "링크가 만료되었습니다" 메시지를 표시하고 사용자가 페이지를 떠나지 않고 교체 링크를 요청할 수 있도록 합니다.
...

패치 (patch)를 수락하기 전 품질 게이트 (quality gate) 하나 추가하기

좋은 브리프는 작업의 시작을 제어합니다. 품질 게이트 (quality gate)는 작업의 종료를 제어합니다.

결과를 수락하기 전에 다음을 질문하세요:

1. 패치가 명시된 결과물을 해결했는가?
2. 가드레일 (guardrails) 내에서 작업이 이루어졌는가?
3. 주장을 뒷받침하는 테스트 또는 명령어 출력 결과가 있는가?
4. 에이전트가 가정 사항과 검증되지 않은 영역을 공개했는가?
5. 디프 (diff)가 합리적인 대안보다 작은가?

마지막 질문이 특히 유용합니다. 결과가 정확하더라도 불필요한 유지보수 작업을 만들어낼 수 있기 때문입니다.

무료 리소스 및 내가 만든 키트

브리프 템플릿과 작은 브라우저 기반 빌더가 포함된 무료 스타터 리포지토리 (starter repository)를 공개했습니다:

• Free AgentBrief repository
• Free interactive brief builder

또한 43개의 재사용 가능한 자산(18개의 태스크 브리프 (task briefs), 12개의 태스크 레시피 (task recipes), 8개의 복구 플레이북 (recovery playbooks), 5개의 품질 게이트 (quality gates))이 포함된 확장 버전인 AgentBrief Pro를 패키지로 구성했습니다. 이는 유료 다운로드($29)입니다: Payhip에서 AgentBrief Pro 보기.

핵심적인 아이디어는 무료로 사용할 수 있습니다: 결과물을 관찰 가능하게 만들고 (make the outcome observable), 의사결정을 변화시키는 컨텍스트 (decision-changing context)를 제공하며, 경계 (boundaries)를 설정하고, 증거 (evidence)를 요구하십시오.