Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 04. 08:38

AI 에이전트가 계속해서 당신의 코드를 망가뜨리는 이유 — 그리고 그 해결책

요약

AI 에이전트가 코드를 망가뜨리는 근본 원인은 인간 중심의 모호한 명세서 형식에 있습니다. 이를 해결하기 위해 불변량(Invariants) 도입, 에이전트 리뷰 단계 추가, '변경하지 말아야 할 것' 섹션 포함 등 기계 친화적인 명세 구조를 제안합니다.

핵심 포인트

  • 기존 명세서는 인간용이며 AI 에이전트에게는 모호함 유발
  • 검증 가능한 규칙인 '불변량(Invariants)' 도입 필수
  • 코드 작성 전 에이전트가 명세를 감사하는 'Agent Review' 단계 필요
  • '변경하지 말아야 할 것' 섹션을 통해 의도치 않은 코드 변경 방지

이런 상황을 상상해 보세요: 당신은 명확하고 구체적인 요구사항을 작성합니다. 에이전트는 그것을 읽고 당신이 쓴 그대로 수행하지만 — 당신이 언급조차 하지 않았던 세 가지 기능을 망가뜨려 놓습니다.

에이전트가 일을 못 해서가 아닙니다. 명세서(spec)가 기계가 아닌 인간 독자를 위해 작성되었기 때문입니다.

인간 개발자는 모호함을 견뎌냅니다. 경험을 통해 빈틈을 채웁니다. 되돌릴 수 없는 일을 하기 전에는 질문을 던집니다. AI 에이전트는 그렇게 작동하지 않습니다. 그들은 학습 데이터(training data)가 제안하는 무엇인가로 빈틈을 채웁니다. 때로는 그것이 괜찮을 수도 있지만, 때로는 오후 시간을 통째로 날려버리기도 합니다.

이 벽에 충분히 부딪힌 후, 나는 더 나은 프롬프트(prompt)를 작성하려는 시도를 멈추고 명세서 형식(spec format) 자체에 대해 생각하기 시작했습니다.

진짜 문제: 명세서 형식이 진화하지 않았다

IEEE 830, ISO/IEC 29148, GOST 34.602. 이 모든 것은 AI 코딩 에이전트가 존재하기 수십 년 전에 작성되었습니다. 모두

INV-001: 외부 npm 패키지 사용 금지
불가능 사항: npm 모듈의 require() 추가 불가
이유: 앱은 npm install 없이 실행되어야 함
...

Check 필드는 이것을 단순한 주석과 다르게 만드는 요소입니다. 이는 검증 가능한 규칙입니다. 불변량 (Invariants)을 도입하기 전에는 "코드베이스를 최소한으로 유지하라"라고 적곤 했는데, 한 에이전트는 이를 npm 패키지 3개를 추가해도 된다는 허가로 해석한 적이 있습니다. 불변량은 그러한 해석의 여지를 제거합니다.

3. 에이전트 리뷰 (Agent Review)

에이전트는 무언가를 작성하기 전에 명세서 (spec)를 감사 (audit)합니다:

  • 섹션 간의 모순 발견
  • 누락된 엣지 케이스 (edge cases) 식별
  • 수락 기준 (Acceptance Criteria)의 완전성 확인
  • 불변량 간의 충돌 여부 검증

강력한 규칙: 3개 이상의 문제 발견 → 중단 후 질문할 것. 진행하지 마십시오.

에이전트가 코드 한 줄을 쓰기 전에 저에게 "명세서에서 5개의 모순을 발견했습니다"라고 말한 첫 순간, 저는 제가 스스로를 위해 얼마나 많은 재작업 시간을 만들어내고 있었는지 깨달았습니다.

4. 변경 명세 (Change Specification)

현재 상태 (Current State) → 목표 상태 (Desired State) → 변경하지 말아야 할 것 (What NOT to change) → 영향 (Impact) → 롤백 (Rollback)

"변경하지 말아야 할 것"은 그 어떤 고전적인 명세 형식에도 존재하지 않는 섹션입니다. 이는 제가 워크플로우에 추가한 것 중 가장 유용한 것입니다.

세 가지 수준

CORE        15–20 페이지   봇, SaaS, API, 자동화 (프로젝트의 80%)
EXTENDED    40–60 페이지   보안, 컴플라이언스 (compliance), 상세 테스트
ENTERPRISE  전체 표준      은행, 규제 산업, AI 플랫폼

5분 만에 시도하기

  1. 1.1 작성 — 무엇을, 누구를 위해 (2문장)
  2. 2.1 작성 — 도메인 용어 사전 (5~10개 용어)
  3. 2.5 작성 — 3~5개의 불변량 (invariants)
  4. 3.2 작성 — 수락 기준 (Acceptance Criteria)을 포함한 사용자 스토리 (user stories)
  5. 2.4 설정 — 기술 스택 (tech stack)

이를 에이전트에게 전달하세요. 코드를 작성하기 전에 에이전트 리뷰 (Agent Review)를 수행하라고 요청하세요. 여러분의 요구사항에서 에이전트가 무엇을 찾아내는지 확인해 보십시오.

→ github.com/Kholomyanskiy/anss-standard

CC BY-NC-SA 4.0. 실제 작성된 두 가지 예시가 포함되어 있습니다. Claude Code, Cursor, GitHub Copilot과 함께 사용할 수 있습니다.

Artem Kholomyanskiy — AI 자동화 컨설턴트, EVAI Consulting

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0