AI Agent는 구현 전에 명령어 하나를 실행하라

서론

AI Agent에게 코드를 작성하게 할 때, 실패의 원인은 구현 능력보다 전제 조건(Premise)을 설정하는 방식에 있는 경우가 많습니다. 저의 경우에도 2026-05-23에 Docker의 실체를 확인하지 않은 채 Oracle ADB를 전제로 이야기를 진행했다가, 나중에 "지금 작동하는 것은 별도의 구성이다"라는 수정 사항이 들어왔습니다. 같은 날 codex exec를 통해 desktop 조작용 경로를 그대로 사용할 수 있다고 착각하여 멈춘 적도 있습니다.

이러한 반성을 바탕으로, 수중에 feedback_verify_environment_before_implement.md를 만들어 "외부 시스템·CLI·DB·컨테이너 전제를 설정하기 전에 명령어 1개로 실재 여부를 확인한다"라는 규칙을 남겼습니다. 추상론이 아니라, 구현 전에 10초 만에 할 수 있는 확인을 먼저 도입하는 것만으로도 불필요한 수정을 줄이기 쉬워집니다.

1. 먼저 망가지는 것은 코드가 아니라 전제

제가 뼈아프게 느꼈던 것은 구현에 들어가기 전의 "아마 이렇게 되어 있을 것이다"라는 추측입니다. 2026-05-25에 정리한 dreams.md에서도 반복되는 실패 패턴으로서 "환경 전제의 미확인으로 인한 오판(Misjudgment)"이 승격 후보로 올라와 있었습니다. 거기에는 발생 사례로 다음 3건이 나열되어 있습니다.

• 2026-05-23: Docker 미확인 상태로 OCI ATP라고 오판
• 2026-05-23: codex exec로 desktop 조작 계열을 그대로 사용할 수 있다고 착각
• 2026-05-19: signal.alarm 미설치로 인해 hang(멈춤) 요인을 간과

여기서 공통된 점은 설계가 나빴다기보다, 관측(Observation) 없이 환경을 추정했다는 것이었습니다. 구현을 시작하기 전에 명령어 1개를 실행했다면, 미리 막을 수 있었을 가능성이 높은 실수입니다.

2. 1개 명령어 확인을 규칙화하면 망설임이 줄어든다

지금은 대상별로 첫 확인 사항을 고정하고 있습니다. feedback_verify_environment_before_implement.md에 적은 내용도 하는 일은 매우 단순합니다.

# CLI가 전제라면
command -v grok
# 컨테이너가 전제라면
...

중요한 것은 "올바른 상세 정보를 전부 수집하는 것"이 아니라, 우선 전제가 실재하는지를 보는 것입니다. 예를 들어 2026-06-06에 Grok Build CLI 도입 절차를 다루었을 때도, 갑자기 설치를 진행하지 않고 설정 파일과 현황을 확인한 뒤 진행한 결과, 이미 도입 및 로그인되어 있음을 알 수 있었습니다. 만약 이 단계를 건너뛰었다면, 불필요한 재설정이나 다른 원인을 놓치는 일이 발생했을 것입니다.

3. 구현 전 확인은 "정중함"이 아니라 비용 절감

이 규칙을 도입한 후 변한 것은 조사 시간이 아니라, 탈선(Detour)의 양입니다. 환경이 없다면 코드를 작성하지 않고 "환경 블로커(Environment Blocker)"로 분류할 수 있고, 환경이 있다면 그 증적을 가지고 다음 단계로 넘어갈 수 있습니다.

특히 AI Agent 운용에서는 확인을 뒤로 미룰수록 피해가 커집니다. 인간이라면 "전에도 여기서 막혔었지"라고 떠올리겠지만, Agent는 그럴듯한 전제 위에 그럴듯한 구현을 쌓아 올리기 때문입니다. 그래서 저는 똑똑한 추론보다 먼저, 투박하더라도 관측을 배치하게 되었습니다.

경험상, 먼저 실행하는 명령어 1개는 "지나치게 보수적인 절차"가 아닙니다. 오히려 나중에 30분을 들여 오판을 청소하지 않기 위한 최단 경로입니다.

또 하나 효과적이었던 것은 확인 결과를 짧게 남기는 것이었습니다. 확인했다고 생각함은 다음 날이면 잊히지만, docker ps로 대상 없음이나 command -v grok 통과와 같이 한 줄로 남겨두면 다음 세션에서 동일한 확인을 할 때의 기점이 됩니다. 저의 운용 방식에서는 이러한 종류의 교훈을 Daily Note로 끝내지 않고, 재사용하고 싶은 것만 feedback_*.md로 승격시키도록 하고 있습니다. 대화 로그 안에 묻어두면 동일한 오판이 다른 project에서 또 발생하기 때문입니다.

요약

• AI Agent의 실패는 구현 그 자체보다 미확인된 전제에서 시작되는 경우가 많음
• 구현 전에 command -v, docker ps, git status -sb, test -f 중 하나만 실행해도 오판을 줄이기 쉬움
• 환경이 없다면 코드 수정이 아니라 환경 블로커로 분류
• 사용자 수정으로 얻은 교훈은 대화로 끝내지 말고 feedback_*.md로 남길 것

짧은 운영 규칙으로 승격시킨다 - AI Agent 운영에서는 "구현 후 검증"보다 "1회 관측 후 구현"이 결과적으로 더 빠르다

Discussion