AI에게 버그 수정을 요청할 때마다 프로젝트 전체를 리팩터링하던 문제를 해결한 방법

AI 도구를 사용하는 개발자라면 누구나 최소 한 번은 이런 경험을 했을 것입니다.

Cursor나 Copilot에게 버그 하나만 고쳐달라고 요청했습니다. 그런데 AI는 8개의 파일을 건드렸습니다. 그중 3개는 버그와 관련이 없었습니다. 그중 하나는 다른 기능을 망가뜨렸습니다. 결국 당신은 AI가 "수정한" 것들을 되돌리는 데 다음 한 시간을 허비하게 됩니다.

이것은 AI의 문제가 아닙니다. 워크플로 (Workflow)의 문제입니다.

AI는 당신이 무엇을 원하는지 전혀 몰랐습니다. 외과 수술처럼 정밀하게 고치길 원했나요? 자유롭게 리팩터링 (Refactor) 하길 원했나요? 먼저 계획을 세우길 원했나요? AI는 알지 못했습니다. 그래서 추측했고, 잘못 추측했습니다.

근본 원인
대부분의 개발자는 모든 작업에 대해 동일한 프롬프트 (Prompt) 워크플로를 사용합니다.
버그 수정. 새로운 기능 추가. 시스템 설계. 빠른 패치. 모두 같은 구조, 같은 기대치, 같은 결과로 이어집니다.
당신이 모든 작업을 동일하게 취급했기 때문에 AI도 이 모든 것을 동일하게 처리합니다. AI에게 운영 컨텍스트 (Operating context)를 제공하지 않았기 때문입니다.

해결책: 운영 모드 (Operating Modes)
저는 이 문제를 해결하기 위해 'Vibe Coding Essentials'를 직접 만들었습니다. 핵심 아이디어는 간단합니다.
프롬프트를 입력하기 전에 모드를 설정하는 것입니다. 모드는 이 특정 작업에 대해 AI가 정확히 어떻게 행동해야 하는지 알려줍니다.

4가지 모드:
[BUILDER] — 새로운 기능 구현. 빠르게 진행. 허용 가능한 트레이드오프 (Tradeoffs). 과도한 엔지니어링 금지.
[MAINTAINER] — 정밀한 수정만 수행. 범위 밖의 것은 건드리지 말 것. 리팩터링 금지. 새로운 의존성 (Dependencies) 추가 금지.
[ARCHITECT] — 코드 한 줄을 쓰기 전에 계획하고 구조를 설계.
[ECONOMY] — 최소한의 출력. 낮은 토큰 (Token) 사용. 불필요한 내용 배제. 불필요한 파일 생성 금지.

사용법은 간단합니다:
[MAINTAINER] 결제 계산기에 회귀 (Regression) 오류가 발생했습니다. calculateTotal 함수만 수정하세요. 먼저 실패하는 테스트를 작성하세요.
[BUILDER] 이메일과 비밀번호를 사용하는 사용자 인증 흐름을 구축하세요. JWT 토큰을 사용하세요. 아직 OAuth는 추가하지 마세요.
[ARCHITECT] 멀티 테넌트 (Multi-tenant) SaaS를 위한 데이터베이스 스키마를 설계하세요. 아직 코드는 작성하지 마세요. 결정 사항과 트레이드오프 (Tradeoffs)만 제시하세요.

시작하는 방법
60초면 충분합니다. 설치도 필요 없고, 의존성도 필요 없습니다.

AGENTS.md 파일을 프로젝트 루트(root)로 복사하세요.
사용 중인 프레임워크에 대한 환각 방지 규칙(anti-hallucination rules)을 AGENTS.md에 붙여넣으세요.
다음 프롬프트(prompt)를 입력하기 전에 모드 태그(mode tag)를 추가하세요.
출력이 변하는지 확인하세요.

그게 전부입니다.

이것을 만든 이유
저는 데였습니다. 여러 번 말이죠.
기능 구현 도중 발생하는 컨텍스트 붕괴 (Context collapse). 날짜 형식을 맞추기 위해 AI가 4개의 패키지를 추가하는 상황. 실제 토큰 비용만 발생시키고 아무것도 배포하지 못한 세션. 코드는 작동하지만 팀원 중 누구도 이해할 수 없는 코드.
저는 모든 실패 사례를 기록하기 시작했습니다. 그러자 패턴이 나타났고, 그 패턴으로부터 '모드(modes)'가 탄생했습니다.
이것은 제가 AI 도구를 본격적으로 사용하기 시작했을 때 이미 존재했기를 바랐던 프레임워크입니다.

철학
모델은 생성합니다. 개발자는 결정합니다. 워크플로우 (Workflow)의 주인은 당신입니다.

기여를 환영합니다 — 특히 아직 문서화되지 않은 AI 워크플로우 실패로 인해 데인 경험이 있다면 더욱 환영합니다.

GitHub: https://github.com/ashp15205/vibe-coding-essentials