단 하나의 Markdown 파일로 내 컴퓨터의 모든 AI 코딩 에이전트가 동일한 규칙을 따르게 만든 방법

저는 Claude Code, GitHub Copilot, OpenAI Codex CLI, 그리고 Cursor를 사용하며, 때로는 같은 날에 이들을 모두 사용하기도 합니다. 각 에이전트는 모두 동일한 방식으로 경로를 이탈합니다. 계획 단계를 건너뛰고, 테스트를 잊어버리며, 오래된 라이브러리 버전을 선택하고, 빌드 도중에 열두 가지 질문을 던지곤 합니다. 그래서 저는 하나의 Markdown 템플릿과, 내 컴퓨터의 모든 에이전트에 동일한 규칙을 적용하는 작은 설치 프로그램을 작성했습니다. 그 설계 방식은 다음과 같습니다.

경로 이탈(Drift) 문제
만약 여러분이 AI 코딩 에이전트에게 "칸반(Kanban) 앱을 만들어줘"라고 말해본 적이 있다면, 다음과 같은 상황을 경험했을 것입니다:

• 여러분이라면 절대 선택하지 않을 기술 스택(Stack)을 선택합니다.
• 스캐폴딩(Scaffolding)을 수행한 뒤, 파일 세 개를 작성하다가 "어떤 데이터베이스를 원하시나요?"라고 묻기 위해 멈춥니다.
• 해피 패스(Happy path)만 작성하고 에러 핸들링(Error handling)은 건너뜁니다.
• 여러분이 상기시켜 줄 때까지 테스트 추가를 "잊어버립니다".
• 학습 데이터(Training data)가 기억하는 대로 3년 전 버전의 라이브러리를 가져옵니다.

이 중 어느 것도 지능의 문제는 아닙니다. 이것들은 워크플로우(Workflow)의 문제입니다. 모델은 진정으로 능력이 있지만, 그 주변의 프로토콜(Protocol)이 결여되어 있는 것입니다.

파편화(Fragmentation) 문제
모든 에이전트는 서로 다른 설정 파일(Configuration file)을 읽습니다:

• GitHub Copilot은 .github/copilot-instructions.md를 읽습니다.
• Claude Code는 CLAUDE.md 또는 ~/.claude/skills/<name>/SKILL.md를 읽습니다.
• Cursor는 .cursorrules를 읽습니다.
• Windsurf는 .windsurfrules를 읽습니다.
• Codex CLI, Cursor, Aider, Windsurf는 모두 AGENTS.md도 읽습니다.

이는 동일한 내용을 말하는 다섯 개의 파일이 존재한다는 뜻이며, 파일 중 하나만 업데이트되어도 즉시 독립적으로 경로가 이탈하게 됩니다. 대부분의 사람들은 도구 하나를 선택하고 나머지는 무시하며, 그 결과 해당 도구에 갇히게 됩니다. 저는 그 반대를 원했습니다. 에디터(Editor)를 바꾸듯 에이전트를 교체하면서도 동일한 운영 규칙을 유지하는 것입니다.

하나의 템플릿으로 여러 파일을 만드는 솔루션
전체 프로젝트는 Markdown 폴더로 구성됩니다. 하나의 단일 진실 공급원(Source-of-truth) 템플릿(SKILL.md)이 있고, 이를 통해 에이전트별 전용 파일들을 생성하는 작은 빌드(Build) 단계가 있습니다. 결과적으로 제 컴퓨터의 모든 에이전트는 동일한 입력값, 동일한 프로토콜, 동일한 품질 게이트(Quality gates)를 읽게 됩니다.

프로토콜 자체는 네 단계로 이루어집니다: 1.

1. 원샷 인테이크 (One-shot intake): 에이전트가 빌드 중간에 질문을 던지는 대신, 한 줄 명령에서 도출된 합리적인 기본값(defaults)과 함께 모든 질문을 초기에 단 한 번의 라운드로 마칩니다. 저는 "go"라고 답하거나 특정 라인을 수정합니다. 그러면 에이전트는 중단 없이 실행합니다. 이것이 가장 큰 단일 개선 사항입니다. 빌드 중간에 경로를 이탈하는 상황의 약 80%를 제거합니다.

2. 코드 작성 전 계획 (Plan before code): 에이전트는 기능(features), 의존성(dependencies), 순서를 나열한 PLAN.md를 작성합니다. 계획이 존재하기 전까지는 코드를 작성하지 않습니다. 당연하게 들리겠지만, 대부분의 에이전트는 실행 중심의 프롬프트(action-shaped prompt)를 받으면 기본적으로 이 단계를 건너뜁니다.

3. Ralph 스타일의 기능 루프 (Ralph-style feature loop): 각 기능에 대해 다음 과정을 거칩니다: 명세(spec) → 실패하는 테스트(failing test) → 구현(implement) → 실행(run) → 실패 시 디버깅 및 재시도(on-fail debug-and-retry) → 통과 시 체크포인트(on-pass checkpoint) → 다음 기능. 저에게 다시 에스컬레이션(escalating)되기 전까지 최대 3번의 재시도 패스(retry passes)를 허용합니다. 재시도 예산(retry budget)은 매우 중요합니다. 이것이 없으면 에이전트는 고장 난 엣지 케이스(edge case)에 매달려 한 시간 동안 헛수고를 할 것입니다. 예산이 있으면, 제가 지켜보고 있지 않을 때 조용히 멈춰버리는 대신 막혔을 때 명확하게 알리며 루프를 종료합니다.

4. 바이너리 품질 게이트 (Binary quality gate): "완료(done)"가 허용되기 전에: 린트(lint) 통과, 타입(types) 통과, 테스트(tests) 통과, 빌드(build) 통과가 이루어져야 합니다. 하나라도 빨간불이 들어오면 다시 루프로 돌아갑니다. "대체로 작동함"은 허용되지 않습니다.

에이전트 간에 동일하게 작동하는 이유
동일한 SKILL.md가 소스(source)이기 때문입니다. 구체화된 에이전트별 파일들은 동일한 프로토콜 본문을 감싸는 포맷팅 래퍼(formatting wrappers)일 뿐입니다. Copilot 버전은 Copilot 프런트매터(front-matter)를 가지고, Claude 버전은 Claude 프런트매터를 가지지만, 규칙 자체는 바이트 단위로 동일(byte-identical)합니다. 부수적인 이점은, 무언가를 테스트하기 위해 Copilot에서 Claude Code로 전환할 때 아무것도 새로 배울 필요가 없다는 점입니다. 에이전트는 동일한 기술을 인식하고, 동일한 인테이크를 실행하며, 동일한 게이트를 통과합니다.

설계 단계부터 로컬호스트 우선 (Localhost-first by design)
일부 사람들을 놀라게 할 명시적인 선택을 하나 했습니다. 이것은 로컬호스트 우선(localhost-first) 방식이라는 점입니다. v1에는 "Vercel에 배포" 단계도, Docker도, 프로덕션 경로도 없습니다. 이유는 간단합니다. 코딩 에이전트에 내장된 모든 "프로덕션 배포(ship to prod)" 기능은 그 버그의 절반을 만들어내는 원인이었습니다. 로컬호스트로 배포하는 것은 결정론적인(deterministic) 문제이지만, 프로덕션으로 배포하는 것은 대화(conversation)의 영역입니다.

이것들을 분리하여 유지하는 것이 에이전트(agent)를 더 잘 작동하게 만듭니다. 솔직히 말해서 스킬 자동 발견(Skill auto-discovery) 기능은 모델마다 다릅니다. Claude는 이를 안정적으로 트리거(trigger)합니다. Codex는 제가 /myvibe를 입력해야 합니다. Copilot은 프롬프트 디렉토리(prompt directory)에서 이를 감지합니다. 이것이 성능이 낮은 모델로부터 당신을 구해줄 수는 없습니다. 베이스 모델(base model)이 코드를 작성할 수 없다면, 어떤 워크플로(workflow)도 이를 구제할 수 없습니다. 이 방식이 하는 역할은 더 일찍, 그리고 더 명확하게 실패하게 만드는 것이며, 그 자체로 개선입니다. 이 도구는 주관적(opinionated)입니다. 만약 당신이 "테스트 우선 실패(failing test first)"나 "3회 재시도 후 질문(three retries then ask)" 방식에 동의하지 않는다면, 이 도구가 마음에 들지 않을 것입니다. 괜찮습니다. 직접 시도해 보세요. 전체 프로젝트는 오픈 소스(open source)이며, MIT 라이선스이고, 텔레메트리(telemetry)가 없으며, 유료 등급도 없습니다. 설치 프로그램은 실행하기 전에 읽어볼 수 있는 약 80줄 정도의 코드입니다. Windows: iwr https://raw.githubusercontent.com/Mohamed201389/myVibe/main/bootstrap.ps1 | iex macOS / Linux: curl -fsSL https://raw.githubusercontent.com/Mohamed201389/myVibe/main/bootstrap.sh | bash 저장소(Repo): https://github.com/Mohamed201389/myVibe 제가 가장 먼저 읽어보라고 권하는 파일은 INTAKE.md입니다. 이것은 "빌드 도중 심문 금지(no mid-build interrogation)"라는 약속이자, 이 키트에서 가장 영향력 있는 아이디어입니다. 원래 수백 번이나 동일한 드리프트(drift) 현상을 겪으면서 작성되었습니다. 피드백은 언제나 환영합니다.