AI 코딩 에이전트에게 줄 수 있는 최고의 지침: '불확실할 때는 덜 하라'

인간 팀원에게 오타 수정을 부탁하면, 고쳐진 오타만 받습니다.

같은 것을 AI 코딩 에이전트에게 요청하면, 오타가 수정되고 주변 함수는 "정리"되며, 두 개의 변수가 이름 변경되고, 오류 처리 개선에 관한 메모까지 받을 수 있습니다.

각 변화 자체는 방어할 만합니다. 하지만 이들이 합쳐지면 10분짜리 검토를 20분으로 만들고, 당신은 요청하지 않은 diff(변경 사항)를 갖게 됩니다.

이 에이전트가 악의적인 것은 아닙니다. 단지 '도움이 되려고' 할 뿐인데, 그 '도움이 되는 것'이 어디까지인지 모르는 것입니다.

원칙

UNIVERSAL-AGENTS.md는 한 문장으로 끝납니다:

불확실할 때는, 더 많이가 아니라 덜 하라.

파일의 나머지 모든 내용은 이 원칙을 상세히 설명합니다. 실제 적용 사례를 살펴보겠습니다.

'유익함'이 곧 '범위 내'는 아니다

25절에는 제가 가장 좋아하는 문장이 있습니다:

변경 사항이 유익하다고 해서 그것이 범위(in scope) 안에 있다는 의미는 아니다.

이 문장은 에이전트의 가장 강한 본능을 겨냥합니다. 원치 않는 변화 대부분은 '좋은 아이디어'입니다: 더 깔끔한 이름, 최신 구문, 두 버전 뒤처진 의존성 등. 이 규칙은 그것들이 개선점일 수 있음을 인정하지만, 요청 자체가 작업을 정의하기 때문에 여전히 거절합니다.

8절에서는 파일을 건드리지 않아도 되는 이유 목록으로 이를 뒷받침합니다: 개선될 수 있다거나, 포맷이 현대화될 수 있다거나, 이름 지정이 더 명확할 수 있다거나, 의존성이 더 최신일 수 있다거나, 테스트가 확장될 수 있습니다. 가능한 개선 사항이 자동으로 요청된 작업의 일부가 되는 것은 아닙니다.

에이전트가 실제 버그를 발견하면 어떻게 할까?

이것이 흥미로운 경우입니다. 작업을 수행하는 동안, 에이전트는 관련 없는 문제를 발견합니다. 8절과 14절은 제한적인 경로를 제시합니다:

다음의 경우에만 수정하라: 요청된 변경 사항이 작동하는 것을 직접적으로 방해하거나, 당신이 명시적으로 수정을 승인한 경우.

그 외의 경우:

• 조용히 고치지 마라.
• 주변 코드를 재설계하지 마라.
• 요청된 작업에 실질적인 영향을 미칠 때만 언급하라.

이는 의도적인 트레이드오프입니다. 에이전트는 검토 과정에서 발견할 변경 사항을 몰래 포함하지 않으며, 여전히 중요한 문제들을 플래그 지정합니다.

요청이 불분명할 때 할 일

적게 하는 것은 추측하지 않는다는 의미도 됩니다. 섹션 2에 따르면, 요청이 모호하거나(ambiguous), 불완전하거나(incomplete), 모순되거나(contradictory), 프로젝트와 충돌하는 경우(in conflict) 에이전트는 다음을 수행해야 합니다:

1. 구현하기 전에 중단한다.
2. 구체적인 모호성 또는 충돌 지점을 식별한다.
3. 필요한 최소한의 질문을 한다.
4. 명확화를 기다린다.

그리고 구현에 실질적으로 영향을 미치는 요구사항은 절대 추측하지 않습니다.

_최소한(minimum)_이라는 단어에 주목하세요. 10개의 명확화 질문을 던지는 에이전트는 추측하는 에이전트만큼이나 성가십니다. 목표는 작업을 막지 않는 한두 개의 날카로운 질문입니다.

우선순위 순서가 논쟁을 해결한다

목표들이 충돌할 때, 섹션 1은 명시적인 순서를 제시합니다: 사용자의 명시적 요구사항(explicit user requirements)이 가장 먼저이며, 그다음으로 정확성(correctness), 안전 및 보안(safety and security), 기존 아키텍처 및 관례(existing architecture and conventions), 최소 범위(minimal scope), 재사용(reuse), 유지보수성(maintainability), 문서화 일관성(documentation consistency) 순입니다.

이러한 순서는 다음을 답변합니다.