1. 들어가며: 바이브 코딩의 유행과 현실적인 고민
2025년 개발 생태계를 뒤흔든 가장 뜨거운 화두는 단연 바이브 코딩이었을 것입니다. 초기 창업팀에서 프로젝트를 시작하는 개발자이자 본격적인 커리어를 준비하는 취업준비생 입장에서, 코드를 뚝딱 만들어내는 AI의 발전 속도는 경이로움을 넘어 일견 채용에 대한 두려움으로 다가오기도 했습니다.
하지만 막연한 불안감에 빠져있기보다는 시각을 조금 바꿔보기로 했습니다. "어떻게 하면 이 강력한 AI를 활용해 우리 팀의 개발 생산성을 극대화할 수 있을까?"
실무에 AI를 도입하며 마주한 현실은 단순히 코드를 복사하는 것만큼 간단하지 않았습니다. 팀원 각자가 파편화된 방식으로 AI를 사용하다 보니, 오히려 팀의 코드 컨벤션을 맞추고 프로젝트 전체의 통일성을 유지하는 데 더 많은 리뷰와 수정 비용이 들 것 같다는 우려가 생겼습니다.
신뢰할 수 있는 서비스를 만들기 위해서, AI의 결과물을 그대로 수용하기보다는 AI가 우리 조직의 언어와 프레임워크 구조 안에서 '제대로' 동작하도록 규칙을 잡아주는 과정이 필요하다는 결론을 내렸습니다.
즉, 단순한 툴 사용을 넘어 조직 차원에서의 체계적인 AI Co-Work 환경이 필요했습니다. 이 글에서는 우리 팀이 Claude Code를 활용해 어떻게 팀 컨벤션에 맞춘 컨텍스트 엔지니어링을 수행했고, 파편화된 AI 사용의 한계를 극복하며 개발 생산성을 어떻게 끌어올리고 있는지 그 과정을 공유하고자 합니다.
2. 컨텍스트 엔지니어링의 목표
팀이 함께 사용할 수 있도록 해야한다.
아직 학생이거나, AI툴을 도입하기 시작한 초기 조직은 조직내 개인이 룰을 정하고 코드를 작성합니다. 이렇게 되면 같은 프로덕트를 만들더라도, 내리는 명령의 종류가 제각각이게 됩니다.
저희는 지금까지 컨벤션이라는 이름아래 동일한 규칙을 지키며 코드를 작성해 왔습니다. AI의 컨텍스트 문서 또한 팀의 규칙을 따르고 이를 일관되게 적용할 수 있어야 합니다.
- Before: 개별 팀원이 각자의 스타일로 프롬프팅 -> 결과물의 일관성 부족
- After: 팀이 합의한 아키텍처, 네이밍 규칙, 기술 스택을 담은 '공통 컨텍스트' 주입 -> 누가 요청해도 동일한 규격의 코드 생성
또한 이와 같은 컨텍스트 문서를 작성하기 위한 규칙이 마련하여 이 역시 팀에서 지키며 수정할 수 있도록 구성했습니다.
토큰을 최대한 아끼면서 구현의 일관성을 가져야 한다.
흔히 LLM을 사용할 때 채팅하듯 여러 번 대화를 주고받으며 수정하는 방식을 사용합니다. 하지만 이 방식은 맥락을 잃고 효율적이지 못합니다.
- 맥락의 휘발: 대화가 길어질수록 AI는 초기 요구사항이나 전체 구조를 놓칠 가능성이 큽니다.
- 비용 문제: 수정 요청을 반복할수록 누적된 토큰 양이 늘어나 비용과 시간이 낭비됩니다.
따라서 미리 정의된 맥락을 주입하고, 필요할 때 마다 어떤 문서를 주입해야할지 명시하여 구현의 일관성과, 토큰 효율을 극대화 시키고자 했습니다.
3. AI를 팀원으로 만들기
글에 들어가기 전 해당 글은 Toss의 소프트웨어 3.0 시대를 맞이하며 라는 글이 큰 도움이 됐습니다. 초기에 구성하신다면 읽어보시길 추천드립니다.
아키텍처 설계: Toss의 레이어드 구조 적용
- Slash Command = Controller 역할
- Sub-agent = Service Layer (여러 기능 조합)
- Skills = 단일 책임 원칙을 따르는 컴포넌트
- MCP = 외부 시스템과의 Adapter
- CLAUDE.md = 프로젝트 설정 파일 (package.json 역할)
이 개념을 프로젝트에 다음과 같이 적용했습니다.
1. Boot Sequence: manifest.md가 부트로더 역할
AI는 매 대화마다 어디서부터 읽어야 할지 모릅니다. 따라서 우리는 manifest.md를 부트로더로 설계했습니다.
# manifest.md
boot_sequence:
- order: 1
file: .claude/core/essential-rules.yaml
purpose: Load constraints & stack
- order: 2
file: .claude/memory.md
purpose: Load context
- order: 3
file: .claude/CLAUDE.md
purpose: Load indexAI는 실행 시 항상 manifest.md를 먼저 읽고, 정해진 순서대로 문서를 로드합니다. 이는 마치 애플리케이션의 main() 함수처럼 작동합니다.
2. Lazy Loading: 필요한 것만 로드시키기
CLAUDE.md는 변하지 않는 정보만 담아야 합니다.
이를 적용하여 문서를 세 단계로 분류했습니다:
Index
- 1. Core (Must Read): 반드시 읽어야 하는 변하지 않는 규칙
- core/essential-rules.yaml: Non-negotiable Rules & Tech Stack
- memory.md: Current Context & Status
- 2. Design (Read on Demand): 설계/구현 시에만 필요한 문서
- core/system-design.yaml: Architecture, API, Entity Rules
- 3. References (Lazy Load): 필요할 때 사용하는 상세 가이드
- references/conventions/coding-style.md: 코딩 스타일 가이드
- references/data-model/domains/: 도메인 엔티티 정보
이를 통해 불필요한 토큰 소비를 줄이고, AI가 핵심 컨텍스트에 집중할 수 있도록 했습니다.
3. Skills: 단일 책임 원칙
반복적인 작업을 Skills로 정의했습니다:
Skills
- /feature: 새로운 기능 구현
- /fix: 버그 수정
- /refactor: 리펙토링
- /docs: 문서화
각 Skill은 명확한 책임을 가지며, 사용자는 /feature라고 입력하는 것만으로 정해진 워크플로우를 실행할 수 있습니다.
Ask Protocol 정의하기
AI 에이전트는 구현, 혹은 수정 중 불확실한 상황에서 질문할 수 있습니다.
이를 적용하여 "Ask Protocol"을 정의했습니다:
Agent Behavior (Protocol)
- Ask Protocol: If requirements are ambiguous, risky (e.g., deletion), or deviate from conventions, STOP and ASK the user immediately.
AI는 다음 상황에서 반드시 사용자에게 질문해야 합니다:
- 요구사항이 애매할 때
- 데이터 삭제와 같이 위험한 작업일 때
- 기존 컨벤션을 벗어나는 작업일 때
이는 모든 분기를 미리 정의할 필요 없이, 중요한 순간에 사용자 판단을 요청하는 방식으로 작동합니다.
Feature Spec: Docs First 워크플로우
Toss 블로그에서는 "변하지 않는 정보만 문서화하라"고 했지만, 우리는 한 가지를 추가했습니다: Feature Spec입니다.
각 기능은 구현 전에 YAML 형식의 명세서를 먼저 작성합니다
예를들어:
# create_remote_waiting.yaml
meta:
id: FEAT-WAITING-002
title: 원격 웨이팅 등록 (Remote Waiting Registration)
type: Feature
overview:
summary: >
앱 사용자가(Member)가 직접 특정 부스에 원격으로 웨이팅을 신청하는 기능입니다.
user_story: >
As a Member, I want to register for waiting remotely via the app,
so that I can enjoy the festival without physically standing in line.
technical_spec:
api:
- method: POST
path: /api/v1/booths/{boothId}/waitings
auth: MEMBER
validation_rules:
- "요청자는 로그인한 회원(MEMBER)이어야 한다."
- "부스가 존재하며, 운영 상태가 'OPEN'이어야 한다."
- "동일한 부스에 이미 'WAITING' 상태인 내역이 존재하면 안 된다."
testing_strategy:
happy_path:
- "로그인한 멤버가 원격 줄서기가 허용된 OPEN 부스에 웨이팅 등록 성공"
edge_cases:
- "부스가 CLOSED 상태일 때 예외 발생 (BOOTH_NOT_OPEN)"
- "이미 웨이팅 중인 회원이 중복 등록 시도 시 예외 발생"
이 문서는 기본적으로 구현 중 변경하지 않는 것을 원칙으로 합니다. 만약 문서를 구현 중간에 수정해야 한다면 AI의 구현을 멈추고, 문서를 수정 후 새 대화를 열어 다시 구현할 수 있도록 합니다.
문서 포맷은 yml로
AI는 구조화 된 포맷일 수록 맥락을 이해하기 쉽고, 토큰 효율적으로 구성할 수 있습니다. 흔히 AI 친화적인 포맷으로 md, xml 등을 꼽습니다.
초기에는 claude는 xml 형식을 잘 이해한다는 글을 읽고, xml 형식으로 spec 문서를 작성했습니다. 하지만 xml 포맷은 치명적인 단점이 있었는데요.
1. XML은 인간에게 친화적이지 못하다.
문서는 기본적으로 인간이 작성할 수 있어야 한다고 생각했습니다. code first가 아닌 docs first로 요구사항을 문서에 먼저 반영하고 이를 구현하게 하는 것이 기본 흐름이기 때문입니다.
문서는 편집하기 쉽고, 빠르게 변경해야 하기에 인간에게 친화적이지 못한 XML 포맷은 적절하지 못하다고 생각하여 다른 포맷으로 변경하기로 했습니다.
2. 마크다운은 자칫 컨텍스트를 나열할 수 있다.
다음으로 AI가 선호하는 포맷은 마크다운이 있었습니다. 실제로 많은 프로젝트에서 마크다운을 사용하고 있는것으로 알고있었습니다. 또한 수정하기 용이하기 때문에 사용을 고려했으나, 모든 상황에서 사용하기에는 어려움이 있다고 판단했습니다.
그 이유는 다음과 같습니다.
1. 불필요한 컨텍스트가 포함될 수 있다.
마크다운은 익숙하게 사용해 왔기 때문에, 문서를 작성하게 되면 서술하는 방식으로 사용되기 쉬울 것이라고 생각했습니다.
맥락을 규격화 해야하는 상태에서 무분별하게 서술하는 방식은 애매한 표현, 그리고 불필요하게 사용되는 연결어 등으로 인해 할루시네이션과 토큰 사용량 면에서 불리할 것이라고 생각했습니다.
2. 위계를 한눈에 보기에 다소 어렵다.
마크다운은 보통 # 을 이용해서 글의 맥락을 나타냅니다. 하지만 이 역시 3계층만 표현할 수 있다는 점에서 위계 표현에 제한이 있다고 생각했습니다.
또한 위계를 한눈에 보기에 다소 불편하다고 생각했습니다.
3. 그래서 최종 선택은 YAML(yml)
앞선 XML과 마크다운의 단점을 보완하면서도, AI와 팀원 모두에게 가장 효율적인 포맷을 고민한 끝 YAML을 컨텍스트 문서의 표준으로 도입하기로 결정했습니다. 그 이유는 다음과 같습니다.
1. 강제되는 구조화와 압도적인 토큰 효율
YAML은 Key-Value 형태를 기반으로 합니다. 이는 문서를 작성하는 팀원으로 하여금 자연스럽게 '줄글 형태의 서술'이 아닌, 핵심 키워드와 '조건(명세)' 위주로 작성하도록 유도합니다. 불필요한 조사나 연결어가 배제되므로 토큰 사용량을 획기적으로 줄일 수 있고, AI 역시 애매한 문장 대신 명확한 속성값으로 맥락을 파악하기 때문에 할루시네이션이 크게 줄어듭니다.
2. 한눈에 들어오는 직관적인 위계(Hierarchy) 표현
마크다운이 # 기호를 통해 다소 평면적인 계층 구조를 가졌다면, YAML은 들여쓰기(Indentation)만으로 복잡한 비즈니스 로직이나 엣지 케이스의 Depth를 무한하고 시각적으로 깔끔하게 표현할 수 있습니다. 덕분에 문서의 전체적인 뼈대와 세부 조건을 한눈에 파악하기 쉬워, 'Docs First'를 실천하며 문서를 리뷰하고 수정하는 과정이 훨씬 수월해졌습니다.
As-Is
To-Be
4. 성과
성과: 모델 1회 요청당 토큰 사용량을 최대 25% 절감 (제한량 기준 20% → 15% 수준으로 최적화)
실제 구현 단계에서 적용했을 때, 기존에 컨벤션이 맞지 않아 자주 변경해야 했던 것에 비해 확실히 컨벤션에 맞게 잘 작성해줍니다.
아키텍처 설계 단계에서 의도했던 manifest 를 통한 라우팅도 적절히 이루어지고 있어요
엄밀하지 않지만 단순한 API 구현 기준으로 1회당, 20%이상 사용된 토큰 사용량이 10% 대에서 안정적으로 구현이 가능해졌습니다.
추가적으로 한 세션에서 한번의 slach command(Skill)을 사용하는것으로
- 이전보다 수정 요청 빈도 감소 (평균 5회 -> 3회미만)
- 컨텍스트가 늘어지지 않아 할루시네이션 감소
하는 효과도 얻을 수 있었습니다.
5. 회고
회고는 매주 하기
매주 저는 컨텍스트 엔지니어링 회고를 진행하고 있습니다.
현재 구현에서 불만족 스러운 부분은 있는가, spec 문서 중 중복되거나, 혹은 명확하지 않은 부분이 있는지 등을 회고하고 있어요
이렇게 매주 새로운 정보가 있다면 적용해보고 어땠는지 고민하며 수정을 거듭하고 있습니다:
부족한 점이 아직 많다
현재 문서를 기반으로 한 엔지니어링에 초점이 되어있으나, hook, mcp같은 고차원 적인 기능을 바로 도입하고 있지는 않습니다.
최근 알게된 클로드 코드 해커톤 우승자의 글을 바탕으로 더욱 고도화 시키기 위해 노력중이에요
더불어 엔지니어링을 위한 툴도 만들면서 더 좋은 환경을 만들기 위해 노력중입니다.
https://github.com/rootTiket/claude-analytics 에서 완성된 프로덕트가 있으니 관심있으시다면 둘러봐주세요 :)
GitHub - rootTiket/claude-analytics
Contribute to rootTiket/claude-analytics development by creating an account on GitHub.
github.com
마치며
지금처럼 AI 와 human in loop으로 작업하기 시작한지 3주가 지나가고 있습니다.
이를 통해 저희 팀은 다음과 같이 변화했어요
1. 명확한 문서 작성을 통한 기획 - 개발 간 도메인 지식 격차 해소
2. 토큰 사용량 감소 및 팀원 모두 AI를 통한 생산성 향상
부족하지만 긴 글 읽어주셔서 감사합니다!
