bkit — Context Engineering으로 Claude Code를 “제대로” 쓰기
2025년 12월, 저는 bkamp.ai라는 서비스를 출시했습니다.
- 11개의 마이크로서비스
- Next.js 기반 포털
- AWS EKS + GitOps (ArgoCD)
- Terraform 인프라
그리고 이 모든 것을 단 9일 만에 프로덕션에 올렸습니다.
개발자는 저 혼자였고,
AI는 Claude Code를 사용했습니다.
이 글은 “빠르게 만들었다”는 이야기가 아닙니다
많은 AI 개발 사례는 이렇게 설명됩니다:
- “AI로 N일 만에 만들었다”
- “프롬프트를 잘 쓰면 된다”
하지만 실제로 9일 동안 개발을 하면서 느낀 것은 완전히 달랐습니다.
AI가 코드를 잘 짜는 것은 맞습니다.
하지만 무엇을 짜야 하는지는 AI가 결정하지 않습니다.
그걸 결정하는 것은 결국:
- 설계
- 규칙
- 작업 단위
- 검증 방식
입니다.
이걸 저는 Context Engineering이라고 정의했습니다.
Context Engineering이란 무엇인가
간단히 말하면:
프롬프트를 잘 쓰는 것이 아니라
AI가 일하는 환경 자체를 설계하는 것
입니다.
예를 들어:
- 설계 문서를 먼저 만든다
- 작업 단위를 문서 기준으로 나눈다
- 결과를 검증하는 규칙을 만든다
- 반복 가능한 사이클을 만든다
즉,
AI는 “작성자”가 아니라
정해진 컨텍스트를 렌더링하는 엔진이 됩니다
bkamp에서 실제로 했던 방식
1. Day 0 — 코드를 쓰기 전에 규칙을 만든다
첫 커밋에는 코드가 없었습니다.
대신 다음을 만들었습니다:
.claude/CLAUDE.md(약 150줄)- 요구사항 문서
- 전략 문서
여기에는 다음이 정의되어 있습니다:
- PDCA 사이클 (Plan → Do → Check → Act)
- 모든 결과는 사람이 검증
- 한국어로 기획, 영어로 코드, 한국어로 커밋
- 작업 단위와 진행 방식
이 100줄 정도의 규칙이 이후 모든 개발을 결정했습니다.
2. 작업 단위는 “기능”이 아니라 “문서”
일반적으로는 이렇게 요청합니다:
- “채팅 기능 만들어줘”
하지만 실제로는 이렇게 작업했습니다:
- “문서 7의 3.2절을 구현해줘”
이 차이는 굉장히 큽니다.
AI 입장에서:
- 기능 → 해석 필요 (불확실성)
- 문서 → 그대로 구현 (결정적)
결과적으로:
출력의 변동성이 거의 사라집니다
3. 하루 = 하나의 PDCA 사이클
개발은 이런 식으로 진행됩니다:
- Plan (설계)
- Do (구현)
- Check (Gap 분석)
- Act (수정)
그리고 이 사이클을 하루 단위로 반복합니다.
이 방식의 장점은:
- 컨텍스트가 항상 최신 상태 유지
- 작업 범위가 명확
- AI가 “지금 무엇을 해야 하는지” 명확
4. 체크포인트를 찍고 과감하게 갈아엎는다
4일차에는 프론트엔드를 전면 재구성했습니다.
하지만 그 전에 반드시 하는 것이 있습니다:
- 롤백 가능한 체크포인트 생성
이렇게 하면:
실패해도 안전
→ 과감한 구조 변경 가능
5. 인프라는 마지막에 한 번에 붙인다
8일차에 하루 동안:
- Terraform
- Kubernetes
- CI/CD
- ArgoCD
를 한 번에 붙였습니다.
이게 가능한 이유는 단순합니다:
이미 그 전에 모든 구조가 정렬되어 있었기 때문입니다
여기서 얻은 핵심 패턴
이 9일 동안 반복된 패턴은 다음과 같습니다:
- 규칙을 먼저 정의한다
- 설계를 먼저 만든다
- 문서를 기준으로 작업한다
- PDCA 사이클로 반복한다
- 체크포인트를 만든다
- 불일치는 문서에서 해결한다
- 코드는 마지막이다
그런데 이걸 계속 유지할 수 있을까?
여기서 문제가 생깁니다.
이 방식은 강력하지만:
사람이 계속 유지하기에는 너무 힘듭니다
- 규칙을 계속 기억해야 하고
- 문서를 계속 맞춰야 하고
- 매번 PDCA를 지켜야 합니다
그래서 만든 것이 bkit입니다.
bkit은 무엇인가
bkit은 Claude Code 플러그인입니다.
하지만 단순한 도구가 아닙니다.
bkamp에서 사용한 작업 방식을
그대로 시스템으로 만든 것입니다
가장 중요한 개념: PDCA = 상태 머신
bkit에서는 PDCA를 이렇게 구현했습니다:
- 상태: plan, design, do, check, act 등
- 전이: 상태 간 이동 규칙
- 가드: 조건 검사
예를 들어:
- 설계와 구현의 일치율이 90% 이상 → 통과
- 아니면 → 자동으로 수정 루프 실행
즉,
“검토 → 수정”이 자동으로 반복됩니다
Context Engineering을 시스템으로 만든 구조
bkit은 다음 요소로 구성됩니다:
- Skills (도메인 지식)
- Agents (역할 기반 행동)
- PDCA 상태 머신
- Context 주입 시스템
- Quality Gate (검증)
- Audit Log (기록)
- Feedback Loop (자동 반복)
이걸 한 문장으로 정리하면:
AI를 쓰는 것이 아니라
AI가 일하는 시스템을 만든다
결과
이 방식으로 얻은 결과는 다음과 같습니다:
- Claude Code 79개 버전 연속 호환
- 4,000+ 테스트, 실패 0
- 200+ CI 검증 규칙
- Docs와 Code 완전 동기화
결론
이건 AI가 더 똑똑해진 이야기가 아닙니다.
인간의 작업이 앞으로 당겨진 이야기입니다
- 설계 먼저
- 규칙 먼저
- 검증 먼저
그 다음에:
- AI가 실행하고
- 시스템이 검증하고
- 사람이 승인합니다
TL;DR
- 프롬프트만으로는 한계가 있다
- Context Engineering이 핵심이다
- AI는 작성자가 아니라 렌더러다
- 워크플로우가 모델보다 중요하다
링크
이 방식에 대해 의견이나 피드백이 있다면 정말 환영합니다.