저는 현재 여러 앱과 작업들을 병렬로 구축하고 있습니다: 폼 백엔드(form backend), WhatsApp 리뷰 알림 도구, 저의 WordPress 플러그인 및 기타 몇 가지 작업들입니다. 이 모든 것에는 Stripe가 필요합니다. 모든 것에는 트랜잭션 이메일(transactional emails)이 필요합니다. 대부분은 Cloudflare Workers, D1, 그리고 R2를 사용합니다.

한동안 저는 매번 AI가 이러한 통합(integrations)을 처음부터 작성하도록 내버려 두었습니다.

그것은 비용이 많이 들었습니다. 그리고 어리석은 일이었습니다.

실제로 일어나고 있었던 일

Claude Code(또는 어떤 코딩 AI든)에게 "Stripe 결제(checkout)를 통합해줘"라고 요청하면, AI가 완성된 구현체로 순간이동하는 것은 아닙니다. AI는 탐색합니다. 작성하고, 평가하고, 조정합니다. 에러를 처리하고, 그 다음 에러 처리 방식을 재고합니다. 웹훅 핸들러(webhook handler)를 어디에 둘지, 어떤 메타데이터(metadata)를 첨부할지, 응답을 어떻게 구조화할지 파악합니다.

이 모든 과정은 토큰(tokens)과 시간을 소모합니다.

이제 이것을 모든 프로젝트에 곱해 보십시오. 제가 새로운 무언가를 시작할 때마다, AI는 제가 이미 해결했던 통합(integrations)에 대한 동일한 멘탈 모델(mental model)을 다시 구축하고 있었습니다.

코드는 보통 잘 나왔습니다. 하지만 저는 이미 내려진 결정들에 대해 토큰과 리뷰 시간으로 비용을 지불하고 있었습니다.

해결책: ai-boilerplates

저는 ai-boilerplates라는 프라이빗 저장소(private repo)를 만들었습니다. 아이디어는 간단합니다: 제가 해결하고 검증한 모든 통합(integration) 패턴을 그곳에 넣어 참조용으로 사용할 수 있게 하는 것입니다.

ai-boilerplates/
  stripe/
    checkout.ts
...

하지만 중요한 부분은 단순히 코드만이 아닙니다. 각 파일 상단에 있는 컨텍스트 블록(context block)입니다:

/**
 * BOILERPLATE: Stripe Checkout Session
 *
...

그 블록이 진짜 가치입니다. AI는 단순히 코드를 복사하는 것이 아닙니다. 의도, 제약 조건, 그리고 이전의 결정들을 이해합니다. AI는 탐색 단계를 완전히 건너뜁니다.

Claude Code에 연결하기

저는 ~/.claude/rules/ai-boilerplates.md에 전용 규칙 파일을 추가했습니다:

## ai-boilerplates

~/ai-boilerplates/에 있는 저장소는 표준 보일러플레이트(boilerplate) 구현을 포함하고 있습니다.
...

CLAUDE.md 대신 rules/에 유지하는 것은 의도된 것입니다. CLAUDE.md는 기술 스택(stack), 컨벤션(conventions), 사용자의 정체성 등 일반적인 프로젝트 컨텍스트(context)를 위한 것입니다. 반면 규칙(rules)은 모듈화되어 있으며 집중되어 있고, 각각 단일 책임(single responsibility)을 가집니다.

이제 모든 프로젝트의 모든 Claude Code 세션은 해당 컨텍스트가 로드된 상태로 시작됩니다. AI는 빌드하기 전에 확인해야 한다는 것을 알고 있습니다.

변경된 점

차이점은 몇 가지 방식으로 눈에 띄게 나타납니다:

해결된 문제에 대한 토큰 소모 감소. AI가 Stripe 웹훅(webhook) 검증이나 Resend 에러 처리 방식을 다시 탐색하지 않습니다. 보일러플레이트(boilerplate)를 읽고, 이를 적응시킨 뒤, 다음 단계로 넘어갑니다.

프로젝트 전반에 걸친 코드 일관성 향상. 동일한 결정 사항(메타데이터 구조, 에러 응답 형태, 로깅 패턴)이 어디에서나 동일하게 나타납니다. 이는 네 개의 코드베이스 사이에서 컨텍스트 스위칭(context-switching)을 할 때 매우 중요합니다.

리뷰 시간 단축. 내가 이미 고민을 끝낸 부분에 대해 AI가 올바른 판단을 내렸는지 의구심을 가질 필요가 없습니다. 결정은 한 번 내려졌고, 문서화되었으며, 그것으로 끝입니다.

비용 측면의 현실성

AI 추론(inference)은 공짜가 아니며, 에이전트(agents)와 서브 에이전트(subagents)가 표준이 됨에 따라 더욱 복잡해질 것입니다. 이미 대규모 기능에 대해 병렬 에이전트를 실행하는 것만으로도 실제 비용이 발생합니다. 중복 작업을 줄이는 모든 것은 동일한 기술 스택을 사용하는 모든 세션, 모든 프로젝트, 모든 팀원에게 걸쳐 복리로 작용합니다.

보일러플레이트 저장소(repo)는 당신이 할 수 있는 가장 저렴한 최적화 중 하나입니다. 설정하는 데 한 시간 정도 걸리지만, 그 이후의 모든 통합(integration) 과정에서 보상을 돌려줍니다.

좋은 보일러플레이트의 조건

모든 코드가 보일러플레이트가 될 가치가 있는 것은 아닙니다. 좋은 후보는 다음과 같은 것입니다:

1. 하나 이상의 프로젝트에 통합되는 것
2. 이미 최소 한 번 이상 디버깅(debug)을 마친 것
3. 명시적인 아키텍처 결정(architectural decisions)을 내린 것

이 세 가지가 모두 해당된다면 문서화하세요. 단순히 한 번 쓰고 버릴 코드라면 굳이 그럴 필요 없습니다.

컨텍스트가 진정한 자산이다

대부분의 개발자는 AI 생산성을 프롬프트(prompts) 관점에서 생각합니다. 즉, 어떻게 더 나은 질문을 할지, 어떻게 더 나은 결과물을 얻을지에 집중합니다. 그것도 타당하지만, 더 큰 지렛대(lever)를 놓치고 있는 것입니다.

진정한 자산은 구조화된 컨텍스트 (structured context)입니다. 보일러플레이트 (Boilerplates)가 하나의 계층이라면, ADR (Architecture Decision Records)은 또 다른 계층입니다. 팀이 어떻게 일하는지를 인코딩하는 규칙들, 즉 결정이 내려진 이유에 대한 공유된 메모리 (shared memory) 말입니다. 그러한 컨텍스트가 존재하고 모든 세션에 로드될 때, AI는 처음부터 시작하는 것이 아닙니다. 여러분이 이미 파악해 놓은 것들 위에 구축해 나가는 것입니다.

이것은 복리로 작용합니다. 해결된 모든 문제는 다음 문제를 더 저렴하게 만듭니다. 문서화된 모든 결정은 토큰 (tokens), 리뷰 시간, 그리고 여러분의 컨벤션 (conventions)을 다시 설명해야 하는 인지적 오버헤드 (cognitive overhead)를 절약해 줍니다.

ai-boilerplates 리포지토리는 시작할 수 있는 작고 구체적인 지점입니다. 하지만 중요한 것은 그것이 만들어내는 습관입니다.