AI와 함께 코딩하며 4,500시간 이상을 보냈습니다. 제가 최종적으로 갖게 된 Claude 코드 설정입니다.
AI 지원 개발을 빠르고, 통제 가능하며, 검증 가능하게 유지하기 위해 제가 사용하는 엔지니어링 지침, 선별된 기술, 그리고 3단계 검토 워크플로우.
목차
1. 이 설정의 배경 이야기
이 리포지토리는 추측성 프롬프트 모음집이 아닙니다.
이는 AI 코딩 에이전트와 함께 소프트웨어를 능동적으로 구축하고, 디버깅하고, 리팩토링하며, 배포하는 과정에서 추정되는 4,500시간 이상을 보낸 끝에 제가 도달한 설정입니다.
[!NOTE]
4,500시간 이상의 수치는 2년이 조금 넘는 기간 동안 매일의 엔지니어링 작업을 통해 하루 평균 약 6시간씩 생산적으로 작업했을 때를 기준으로 한 개인적인 추정치입니다. 자동 추적되는 원격 측정(telemetry) 데이터가 아닙니다.
제 일상적인 워크플로우는 여러 AI 개발자 도구의 물결을 거치며 진화했습니다:
- 인라인 완성 및 다중 파일 에이전트 편집을 위한 Cursor.
- 자율 터미널 기반 작업 루프 및 마이크로 디프(micro-diff) 검사를 위한 Claude Code CLI.
- 다중 에이전트 워크플로우, 스킬 아키텍처, 백그라운드 자동화를 위한 Antigravity IDE & Gemini CLI.
- API 계약, 컨텍스트 제한, 도구 호출에 대해 다양한 모델들이 어떻게 추론하는지 탐색한 Codex, OpenCode, Amazon Q.
저는 이 모든 플랫폼에서 동등하게 사용했다고 주장하지 않습니다. 수천 시간에 걸쳐 이 모든 것을 경험하면서 명확해진 것은 보편적인 패턴이었습니다:
제약 없는 AI 코딩 에이전트는 예측 가능한 방식으로 실패합니다.
그들은 확증 편향(confirmation bias)을 겪고, 단순 유틸리티를 추측성 일반 프레임워크로 과도하게 설계하며, 환각된 API에 맞춰 코드를 작성하고, 인접 파일을 조용히 재포맷하며, 실제로 실행하지 않고 "테스트 통과!"를 선언합니다.
이 저장소는 그러한 실패 모드를 줄이기 위해 제가 구축한 가드레일(guardrails), 프롬프트, 행동 지침을 나타냅니다. 이는 실제 프로덕션 작업을 위해 설계된 실용적이고 개인적인 설정입니다.
2. 핵심 엔지니어링 철학 (Core Engineering Philosophy)
| 원칙 | AI 지원 엔지니어링에서 중요한 이유 |
|---|
| 1. 속도보다 정확성 | 10초 만에 500줄을 작성하는 에이전트는 그중 20줄이 조용한 레이스 컨디션(race conditions)을 도입하거나 API 계약을 깨뜨린다면 위험 요소입니다. |
| ... | |
참고: CLAUDE.md의 승인 게이트는 에이전트가 따르는 행동 지침일 뿐, 기계적으로 강제되는 보안 경계가 아닙니다. 실제 강제는 코딩 도구의 네이티브 권한 설정에서 나옵니다.
3. 세 가지 프롬프트 검토 워크플로우 (The Three-Prompt Review Workflow)
에이전트가 사용자 프롬프트에서 코드 편집으로 바로 점프하는 것을 허용하기보다는, 비자명한 엔지니어링 작업은 구조화된 진행 과정을 따릅니다:
flowchart TD
User([작업 요청]) --> Classify{작업 수명 주기}
Classify -->|스파이크 / 바운디드| Quick[직접 TDD 및 최소 수정]
...
수명 주기 라우팅 (Lifecycle Routing)
Spike: 저렴한 탐색 명령 1개 -> 문장 2개 분량의 발견.
Bounded: 격리된 복구 및 비파괴적 개선 사항을 다룹니다. 공개 API 계약, 데이터베이스 스키마 또는 금융 로직을 변경하는 경우 먼저 채팅에서 승인을 요청하고, 그렇지 않으면 자율적으로 실행합니다.
Architectural: 서브시스템, 다중 서비스 기능 또는 계약 위반 변경 사항을 다룹니다 -> 아래의 3단계 검토 파이프라인을 엄격하게 실행합니다.
Stage 1: Planning (prompts/planning.md)
- 직무(Job): 저장소를 검사하고, 요구사항을 인수 기준(acceptance criteria)에 매핑하며, 각 기준이 어떻게 검증될지 정의합니다.
- 안전 경계(Safety Boundary): 하드 지침: "계획이 저장되면 멈추고 제 승인을 기다리세요. 구현 코드는 건드리지 마세요."
- 방지하는 것: 환각된 파일 경로(hallucinated file paths), 잘못된 패키지 버전, 또는 부정확한 아키텍처 가정에 기반한 성급한 코드 생성.
- 시각적 아키텍처 모델링(Visual Architecture Modeling): 작고 직접적인 흐름의 경우 인라인 Mermaid 다이어그램이 잘 작동합니다. 하지만 아키텍처가 여러 서비스, 교차하는 클래스 의존성(cross-cutting class dependencies), 또는 진화하는 비즈니스 로직을 포함하게 되면, 텍스트만으로는 통합 사각지대(integration blind spots)를 가릴 수 있습니다. 그러한 시나리오에서는 접근 방식을 확정하기 전에 시각적 모델을 생성합니다. 깔끔하고 편집 수준의 아키텍처 다이어그램을 만들기 위해 Cathryn Lavery의 diagram-design를 자주 참고합니다.
Stage 2: Critical Plan Review (prompts/critical-plan-review.md)
- 직무(Job): 단 한 줄의 코드가 작성되기 전에 독립적인 선임 수석 엔지니어(senior principal engineer)로서 계획에 대한 레드팀 테스트(red-teaming)를 수행합니다. 확증 편향(confirmation bias)을 줄이기 위해 새로운 컨텍스트 또는 서브 에이전트에서 실행됩니다.
- 초점: 레이스 조건(race conditions), 누락된 오류 경계(missing error boundaries), 타임아웃 정책(timeout policies), 아이덴티피티 위험(idempotency risks), 과도한 엔지니어링(over-engineering)을 식별합니다.
- YAGNI 브레이크: 모델이 진정한 실패 모드와 낮은 확률의 가상 엣지 케이스(hypothetical edge cases)를 명시적으로 구별하도록 강제하여, 추측성 복잡성이 시작되기 전에 이를 중단시킵니다.
- 방지하는 것: 에이전트가 나중에 전체 재작성을 필요로 하는 아키텍처 결함을 자신 있게 실행하는 것을 막습니다.
스테이지 3: 프로덕션 준비성 검토 (prompts/production-readiness-review.md)
- 작업 내용: 원본 git 상태(
git status, git diff, git diff --cached, 그리고 추적되지 않은 파일)를 승인된 계획과 대조하여 감사합니다. 새로운 컨텍스트나 서브 에이전트에서 실행됩니다.
- 초점: 논리 버그, 널 포인터 경계(null-pointer boundaries), 통합 오류(integration breaks), 비밀 정보 유출(secrets leakage), 그리고 커밋되지 않은 아티팩트를 찾습니다.
- 개선 규칙: 확인된 문제는 가장 작고 목표 지향적인 편집으로 수정합니다. 만약 수정이 아키텍처 변경을 요구하거나 공개 계약(public contracts)을 변경한다면, 반드시 멈추고 먼저 질문해야 합니다.
- 방지하는 것: 고아화된 추적되지 않은 파일 병합, 깨진 스테이징 diff, 약해진 테스트 단언(test assertions), 또는 미관상의 리포맷팅 회귀(cosmetic reformatting regressions).
4. 선별된 스킬 및 상위 출처 기여 (Upstream Attribution)
수많은 중복되고 노이즈가 많은 플러그인을 쌓는 대신, 이 설정은 신중하게 선택된 오픈 소스 스킬 팩의 간결한 모음을 통합합니다.
[!TIP]
전역 설계: CLAUDE.md는 전역 지침 세트(사용자의 글로벌 ~/.claude/CLAUDE.md로 사용되거나, GEMINI.md / 에이전트 시스템 프롬프트에 맞춰 조정됨)로 설계되어, 접하는 모든 프로젝트에서 기본 엔지니어링 동작을 확립합니다. prompts/의 세 가지 검토 프롬프트는 고객 코드베이스에 커밋되기보다는 비자명한 작업(non-trivial tasks) 중 프롬프트 접미사로 사용되는 개인 운영 템플릿입니다.
Superpowers
Repository: obra/superpowers by Jesse Vincent (Obra)
License: MIT
Jesse Vincent의 superpowers 스위트는 에이전트 기반 개발(agentic development)을 위한 기초 프로세스 규율을 제공합니다:
| Skill | Upstream Runbook | Role in This Setup |
|---|
using-superpowers | skills/using-superpowers | 세션 시작 시 워크플로우 규율을 확립하는 메타컨트롤러 (Metacontroller). |
| ... | | |
Ponytail
Repository: DietrichGebert/ponytail by Dietrich Gebert
License: MIT
AI 모델은 본질적으로 상용구 코드(boilerplate)를 생성합니다. 날짜 유틸리티를 요청하면, moment.js를 설치하거나 일반적인 시간 여행 클래스를 작성할 수 있습니다. ponytail은 **"게으른 시니어 개발자(Lazy Senior Developer)"**의 사고방식을 강제합니다:
- Ponytail 사다리:
YAGNI -> 기존 코드베이스 유틸리티 -> 표준 라이브러리 -> 네이티브 플랫폼 API -> 설치된 종속성 -> 최소 작동 코드.
- 수술적 편집(Surgical Edits): 요청을 충족하는 데 엄격하게 필요한 줄만 수정합니다. 관련 없는 서식 변경이나 인접한 리팩토링은 금지됩니다.
- 근본 원인 초점(Root-Cause Focus): 증상을 하류에서 감싸는 것이 아니라, 호출자가 발생하는 문제 자체를 해결합니다.
ADHD가 있습니다 (I Have ADHD)
저장소: ayghri/i-have-adhd by ayghri
라이선스: MIT
이것은 테스트 또는 정확성 프레임워크가 아닌, 상호작용 및 커뮤니케이션 선호도입니다:
- 답변으로 시작: 첫 문장에서 직접적인 명령, 파일 경로 또는 발견 사항을 제시합니다.
- 분할된 정보(Chunked Information): 인지 과부하를 피하기 위해 글머리 기호 목록은 5개 항목으로 제한합니다.
- 외부화된 진행 상황: 다단계 마이그레이션 시
Step X of Y를 표시합니다.
- 대화적 노이즈 제로(Zero Conversational Noise): 인사말, 가짜 시간 추정치, 동기 부여 클로징 멘트를 제거합니다.
5. 저장소 구조 (Repository Structure)
my-ai-coding-workflow/
├── README.md # 아키텍처, 철학 및 출처 표기
├── CLAUDE.md # 마스터 엔지니어링 지침(Claude Code 및 전역 규칙)
...
- **
CLAUDE.md**는 엔지니어링 지침과 규칙을 위한 마스터 참조 템플릿입니다. Claude Code에서는 이를 글로벌 ~/.claude/CLAUDE.md에 배치합니다. 이는 개별 저장소(백엔드, 프론트엔드, 마이크로 서비스)를 건드릴 때마다 적용되며, 개별 저장소를 오염시키지 않습니다.
- **
prompts/**에는 세 가지 순차적 검토 프롬프트가 포함되어 있습니다. 이들을 개인 프롬프트 관리자, 메모 또는 IDE 스니펫에 저장하여 아키텍처 빌드 시 프롬프트 접미사로 추가하십시오.
6. 채택 가이드 (Adoption Guide)
Step 1: 전역 지침 설정 (Set Up Global Directives)
프로젝트 리포지토리마다 설정 파일을 커밋하는 대신, 글로벌 AI 코딩 에이전트 구성에 CLAUDE.md를 한 번만 설정합니다:
- Claude Code CLI:
CLAUDE.md를 전역 ~/.claude/CLAUDE.md로 복사합니다.
- Gemini CLI / Antigravity: 이 지침들을 전역
~/.gemini/GEMINI.md에 추가합니다.
- Cursor: 해당 지침들을 Cursor Settings > Rules (User Rules)에 붙여넣습니다.
사용자가 여는 모든 리포지토리는 즉시 라이프사이클 라우팅(lifecycle routing), 위험 승인 게이트(risk approval gates), Ponytail ladder, 아이뎀포턴시(idempotency), 그리고 검증 규칙을 상속받게 됩니다.
Step 2: 세 가지 프롬프트 사용하기 (Use the Three Prompts as Suffixes)
파일들을 개인 프롬프트 툴킷이나 스니펫 관리자 내의 prompts/ 폴더에 보관합니다. 사소하지 않은 아키텍처 변경 작업을 할 때는 이 파일들을 프롬프트 접미사(suffix)로 사용하세요:
- 기능 계획 시:
prompts/planning.md 내용을 프롬프트 끝에 추가합니다:
<요구사항 설명>
---
<Append prompts/planning.md>
- 계획 레드팀 검토 시 (Red-teaming): 새로운 컨텍스트나 서브 에이전트를 열고, 초안 계획을 붙여넣은 후
prompts/critical-plan-review.md를 추가합니다.
- 병합 또는 완료 직전:
prompts/production-readiness-review.md로 에이전트에 최종 점검을 요청하여 원본 git diff를 감사하고 테스트 통과 여부를 검증합니다.
7. 크레딧 (Credits)
모든 상위 기술(upstream skills) 및 참조된 도구는 각 개발자에게 속하며, 원래의 오픈소스 라이선스 하에 사용됩니다:
AI 에이전트와 함께 실제 시스템을 수천 시간 동안 구축하며 제작된 Vaibhav의 작품입니다.