artemiimillier/bulletproof: AI 에이전트를 위한 아이디어부터 프로덕션까지의 완전한 개발 방법론

AI 에이전트를 위한 완전한 개발 방법론. 아이디어부터 프로덕션까지.

시스템이 없는 AI 에이전트는 혼란스러운 코드 생성기에 불과합니다. 이들은 작업을 이해하기도 전에 코딩을 시작하고, 최선의 해결책 대신 첫 번째로 떠오른 해결책을 선택하며, 버그가 아닌 것을 "버그를 찾았다"고 말하고, 작업의 절반도 끝나지 않았는데 "완료"라고 말합니다. Bulletproof는 그 혼란을 규율(discipline)로 바꿉니다.

저자: Artemiy Miller · GitHub · Telegram · Channel · Email

당신은 기능을 설명합니다. AI는 코드를 작성합니다. 보기에는 좋습니다. 하지만 그 후에는 다음과 같은 일이 발생합니다:

• 잘 작동하던 무언가를 망가뜨림
• 존재하지 않는 버그를 "수정"하고 실제 버그를 생성함
• 아무도 건드려 달라고 요청하지 않은 코드를 리팩터링(refactoring)함
• 수락 기준(acceptance criteria)의 절반도 충족되지 않았는데 "완료"라고 말함
• 최선의 해결책이 아닌, 머릿속에 가장 먼저 떠오른 해결책을 선택함
• 다음 날 아침, AI가 프로젝트의 전체 아키텍처(architecture)를 무시했다는 사실을 깨달음

AI 에이전트의 75%가 작동 중인 코드에 회귀(regression)를 유발합니다 (SWE-CI 벤치마크, Alibaba 2025). 이것은 AI의 문제가 아닙니다. 프로세스(process)의 문제입니다.

Bulletproof는 12단계 워크플로우(workflow)입니다. 모든 단계는 해당 단계가 없으면 특정 부분이 망가지기 때문에 존재합니다. 모든 작업이 12단계를 모두 거치는 것은 아닙니다. 버그 수정은 6단계를 거치고, 기능 추가는 10단계를 거치며, 아키텍처 변경은 12단계 전체를 거칩니다.

각 단계에서 일어나는 일은 다음과 같습니다:

고통스러운 지점: AI가 바로 코딩으로 뛰어듭니다. 코드베이스(codebase)를 연구하지 않고, 기존 해결책을 찾아보지 않으며, 문맥(context)을 이해하지 못합니다.

Bulletproof가 하는 일: AI가 병렬 연구 에이전트(parallel research agents)를 실행합니다. 각 에이전트는 프로젝트 구조, 패턴(patterns), 의존성(dependencies), 테스트(tests) 등 서로 다른 영역을 깊이 파고듭니다. 동시에 웹을 검색합니다: 누가 이미 이 문제를 해결했는가? 어떤 라이브러리(libraries)가 존재하는가? 검증된 베스트 프랙티스(best practice)는 무엇인가?

핵심 사항: 출력물은 단순한 옵션 목록이 아닙니다. 그것은 구체적인 권장 사항입니다: "Y라는 이유로 X가 최선의 접근 방식입니다." AI는 선택권을 당신에게 떠넘기는 것이 아니라, 스스로 결정을 내리고 이를 방어해야 합니다.

문제점(The pain): AI는 무엇을 정확히 해야 하는지 정의하지 않고 코딩을 시작합니다. '완료'의 기준이 없습니다. 결국 잘못된 것을 만들거나, 너무 많은 것을 만들어버립니다.Bulletproof가 제공하는 것: 우리가 무엇을 만들고 왜 만드는지에 대한 명세서(specification)를 만듭니다. 어떻게 할지는 제외하고 오직 무엇만 정의합니다. AI가 나중에 논쟁할 수 없는 '완료'에 대한 객관적인 측정 기준인 명확한 승인 기준(acceptance criteria)이 포함됩니다.핵심: 이 명세서는 **계약서(contract)**입니다. AI가 5단계에서 자신의 작업을 검토할 때, 이는 그저

단계 사이를 연결하며 인수인계 문서(handoff documents)를 통해 컨텍스트를 전달합니다. AI는 항상 자신의 "스마트 존(smart zone)" 내에서 작업합니다.

문제점 (The pain): AI가 "완료"되었다고 말하지만, 기준의 절반은 충족되지 않았습니다. 또는 아무도 요청하지 않은 추가 작업을 수행하기도 합니다.

Bulletproof의 해결책: AI가 명세서(spec)를 열고 모든 수락 기준(acceptance criterion)을 하나씩 검토합니다: 구현되었는가? 코드의 정확히 어느 부분에 있는가? 작업의 일부가 아니었던 내용이 포함되어 있는가?

핵심 사항: 느낌(vibes)에 기반하여 확인하지 않습니다. **계약서(the contract)**를 기준으로 확인합니다. 모든 기준에 대해 예 또는 아니오로 판단합니다. 만약 '아니오'라면, 다시 돌아가서 완료해야 합니다.

문제점 (The pain): AI가 버그가 아닌 것을 "버그"라고 찾아냅니다. 고장 나지 않은 것을 고칩니다. 실제 문제를 일으키는 "개선"을 수행합니다.

Bulletproof의 해결책: 3단계 점검을 수행합니다. 1단계 - 오류(로직, 보안, 성능) 찾기. 2단계 - 모든 버그가 실제임을 증명하기. 재현 가능한가? 아니오? 그렇다면 그것은 버그가 아니므로 건드리지 마십시오. 3단계 - 로직 및 효율성 검토.

핵심 사항: 규칙은 **"미적 요소나 만약을 위해서 코드를 수정하지 마라"**입니다. 증명 없는 모든 수정은 새로운 버그를 유발할 위험이 있습니다. 초기 AI 코드 리뷰어들은 실제 버그 1개당 9개의 거짓 양성(false positives)을 표시했습니다 (Anthropic). 이 단계는 낭비되는 작업의 90%를 제거합니다.

문제점 (The pain): 코드는 작동합니다. 하지만 다른 어딘가에서 무언가를 망가뜨렸습니다. 일주일 후에야 이를 알게 됩니다.

Bulletproof의 해결책: 머지(merge) 전 필수 점검 사항: (1) 변경된 파일에 의존하는 모듈은 무엇인가? 현재 단계뿐만 아니라 프로젝트의 모든 테스트를 실행하십시오. (2) 계약(contracts) 중 변경된 것이 있는가 - API, 타입(types), 인터페이스(interfaces)? 모든 소비자(consumers)가 업데이트되었는가? (3) 한 달 뒤에 무엇이 잘못될 수 있는가? 데이터가 전혀 없을 때? 백만 개의 레코드가 있을 때? 동시 요청(concurrent requests)이 발생할 때?
(4) 하위 호환성(Backward compatibility)은 유지되는가? 마이그레이션(Migrations)이 필요한가?

핵심 사항: AI 에이전트의 75%가 작동하던 코드를 망가뜨립니다 - 바로 이 단계가 존재하지 않기 때문입니다. 의존성 그래프 분석(Dependency graph analysis)은 회귀(regressions)를 70% 감소시킵니다 (TDAD/arXiv).

모든 단계 완료 - 프로젝트 전체에 걸친 전체 테스트 스위트(test suite). 감사(Audit): 명세서의 모든 내용이 실제로 구현되었는가?

문제점: AI가 자신의 코드를 검토하고 그것이 훌륭하다고 생각합니다.

Bulletproof가 하는 일: 새로운 세션. 신선한 컨텍스트 (Context). 구현 내용을 본 적이 없는 별도의 에이전트. 엣지 케이스 (Edge cases), 레이스 컨디션 (Race conditions), 보안, 성능을 점검합니다.

핵심 사항: AI가 AI를 검토하되, 구현자의 편향 (Bias) 없이 수행합니다. 중요한 코드의 경우 여전히 인간이 필요하며, Bulletproof는 이를 명시적으로 밝힙니다.

자동 취약점 스캐닝 (Automated vulnerability scanning). AI가 생성한 코드는 인간이 작성한 코드보다 보안 문제가 2~3배 더 많습니다. 이것이 그 문제들을 잡아냅니다.

문제가 발견되었나요? 증명된 버그만 수정하십시오 (6단계 규칙이 여전히 적용됩니다). 수정 후에는 영향 분석 (Impact analysis)을 다시 실행하십시오. 수정 작업은 초기 개발보다 코드를 더 자주 망가뜨립니다.

계획을 아카이브(Archive)합니다. 스쿼시 머지 (Squash merge)를 수행합니다. 배포(Deploy)는 당신이 명시적으로 명령할 때만 수행됩니다.

이 단계는 단계들 외부에 존재합니다. 이는 AI가 작업을 마무리하려고 시도할 때마다 실행되는 중단 훅 (Stop hook)입니다. 다음 사항을 점검합니다:

• AI가 불완전한 작업을 합리화하고 있는가? ("기존 문제", "범위 외", "후속 조치를 위해 기록해 두겠습니다")
• 실제로 수정하지 않고 문제점만 나열하고 있는가?
• 변명을 늘어놓으며 실패한 테스트를 건너뛰고 있는가?
• 작업과 관련 없는 변경을 수행하고 있는가?
• 검증 (Verification)을 실행하지 않고 "완료"되었다고 주장하는가?

만약 그렇다면 - **완료를 차단 (Blocks completion)**하고 AI를 다시 작업 완료 단계로 돌려보냅니다.

모든 작업에 12단계가 모두 필요한 것은 아닙니다:

크기	내용	단계
S - 버그 수정, 1-2개 파일	경량 (Lightweight)	조사 (Research) → 구축 (Build) → 자체 감사 (Self-Audit) → 검증 (Verify) → 영향 (Impact) → 게이트 (Gates)
M - 기능 추가, 3-10개 파일	표준 (Standard)	1~10단계
L - 아키텍처, 10개 이상의 파일	전체 파이프라인 (Full pipeline)	모든 12단계

이론이 아닙니다. 모든 메커니즘은 연구 결과에 근거합니다:

메커니즘	출처
40% 컨텍스트 규칙 (40% context rule)	HumanLayer
...

• 당신은 AI로 일회용 프로토타입이 아닌 실제 제품을 만들고 있습니다.
• 데모에서는 작동하지만 프로덕션(Production)에서는 깨지는 코드에 지쳤습니다.
• 한 줄의 수정부터 새로운 마이크로서비스 (Microservice)까지 확장 가능한 시스템이 필요합니다.

# 프로젝트에 적용하기
mkdir -p .claude/skills && git clone https://github.com/artemiimillier/bulletproof.git .claude/skills/bulletproof
# 글로벌 (모든 프로젝트)
...

Open Claude Code → /bulletproof 입력

→ 완료.

또는 단순히 작업 내용을 설명하세요. Claude가 관련이 있다고 판단하면 자동으로 Bulletproof를 채택합니다.

Claude Code · Codex · Cursor · Gemini CLI · Windsurf · OpenCode - Agent Skills 표준을 지원하는 모든 도구.

bulletproof/
├── SKILL.md # 전체 12단계 워크플로우 (Workflow)
├── templates/ # 아티팩트 (Artifact) 템플릿 (연구, 사양, 계획, 인수인계)
...

기여(Contributions)를 환영합니다. CONTRIBUTING.md를 참조하세요.

MIT

Artemiy Miller · Telegram · Channel · Email