[ Claude Code #2 ] SDLC (Software Development Life Cycle): 하네스 엔지니어링과 실무 워크플로우

by

지난 편에서 Claude Code의 설치와 기본 사용법을 익혔다면, 이제는 이를 어떻게 실제 상용 수준의 프로젝트 개발 사이클에 통합할 것인가를 고민해야 할 때입니다. 단순히 “코드를 짜줘”라고 요청하는 ‘바이브 코딩(Vibe Coding)’은 토큰 소모와 코드 부채만 늘릴 뿐입니다.

이번 포스팅에서는 Claude Code를 활용한 명세 기반 개발(Spec-Driven Development)과 AI 에이전트의 불확실성을 제어하는 하네스 엔지니어링(Harness Engineering)의 실무 워크플로우를 딥다이브합니다.

1. AI 코딩의 함정, ‘바이브 코딩’에서 ‘명세 기반 개발’로의 전환

대부분의 개발자가 AI를 쓸 때 범하는 실수는 명확한 설계 없이 프롬프트만으로 기능을 구현하려 한다는 점입니다. 이를 이른바 ‘바이브 코딩(Vibe Coding)’이라 부릅니다.

바이브 코딩의 한계

  • 컨텍스트 오염: 대화가 길어질수록 AI는 초기 아키텍처 결정을 잊고 임시방편적인(Ad-hoc) 코드를 생성합니다.
  • 낮은 재현성: 같은 프롬프트에도 결과물이 매번 달라지며, 운영 환경에서 신뢰할 수 없는 코드가 섞입니다.
  • 비용 폭발: 불필요한 시행착오가 반복되면서 프롬프트 캐싱 효율이 떨어지고 비용이 증가합니다.

이를 극복하기 위해 필요한 것이 명세 기반 개발(Spec-Driven Development)입니다. 구현을 시작하기 전에 AI와 함께 ‘무엇을(What)’ 할지 명확히 정의하고, 이를 문서화(spec.md, plan.md)하여 AI가 이 궤도를 벗어나지 못하게 가이드를 제공하는 것이 핵심입니다.

Claude code - SDLC

2. 설계가 반이다: ‘Plan Mode’를 활용한 아키텍처 중심 개발

Claude Code에는 실행(Act) 전에 생각(Think)하도록 강제하는 ‘Plan Mode’가 내장되어 있습니다. 복잡한 기능을 구현할 때 바로 코드를 수정하게 하지 말고, 다음 워크플로우를 따르십시오.

실무 워크플로우: Plan -> Spec -> Implement

  1. Plan Mode 진입: claude 실행 후 /plan 명령어나 자연어로 아키텍처 설계를 먼저 요청합니다.
  2. 의사결정 매트릭스 작성: 여러 구현 옵션을 제안받고, 보안/성능/유지보수 측면에서 최적의 안을 선택합니다.
  3. plan.md 생성: 결정된 사항을 프로젝트 루트의 plan.md에 기록합니다. 이 파일은 이후 구현 단계에서 Claude의 북극성(North Star) 역할을 합니다.

Bash

# Claude에게 설계를 먼저 시키는 프롬프트 예시
"새로운 인증 모듈을 추가하려고 해. 코드를 짜기 전에 먼저 Plan Mode에서 
기존 아키텍처와 호환되는 설계안을 세 가지 제안하고, plan.md에 정리해줘."

3. 품질을 강제하는 기술: Hooks와 Skills를 활용한 하네스 엔지니어링

“모델은 상품(Commodity)이고, 하네스(Harness)가 해자(Moat)다.”라는 말이 있습니다. AI 모델 자체의 성능보다, 모델이 생성한 코드를 검증하고 제어하는 제어 장치(Harness)를 얼마나 잘 설계했느냐가 프로덕션 품질을 결정합니다.

Hooks를 이용한 결정론적 게이트웨이 구축

Claude Code의 settings.json을 통해 특정 도구 실행 전후에 Hooks를 설정할 수 있습니다. 이는 AI의 실수를 실시간으로 차단하는 ‘안전망’입니다.

  • PreToolUse (예방): rm -rf나 git reset --hard 같은 파괴적인 명령어를 감지하여 차단합니다.
  • PostToolUse (검증): 코드가 수정된 후 반드시 lint나 unit test를 통과해야만 다음 단계로 넘어가도록 강제합니다.

예시: 보안 및 품질 하네스 설정 (.claude/settings.json)

JSON

{
  "hooks": [
    {
      "pattern": "bash",
      "preToolUse": "scripts/security_gate.sh",
      "postToolUse": "npm run lint && npm test"
    }
  ]
}

4. 복잡한 과제 해결을 위한 멀티 에이전트 전략: Subagents 활용

단일 Claude 세션에서 모든 것을 해결하려 하면 컨텍스트가 너무 무거워져 추론 능력이 저하됩니다. 이때 Subagents 기능을 활용하여 역할을 분담해야 합니다.

역할별 Subagent 구성

  • Reviewer Agent: 작성된 코드가 프로젝트의 컨벤션을 준수하는지 비평만 수행합니다.
  • Debugger Agent: 테스트 실패 시 원인을 분석하고 수정안만 제안합니다.
  • Data Scientist Agent: 복잡한 SQL 쿼리나 데이터 분석에 특화된 모델(예: Sonnet 3.5)을 사용하도록 설정합니다.

subagents/reviewer.md 파일을 통해 해당 에이전트의 페르소나와 제한 사항을 정의할 수 있으며, 이는 메인 에이전트의 부담을 획기적으로 줄여줍니다.

5. 지속 가능한 개발 환경 구축: CLAUDE.md와 Context 관리

AI 에이전트가 프로젝트의 문맥을 완벽히 이해하게 만드는 가장 강력한 도구는 바로 CLAUDE.md입니다.

CLAUDE.md의 핵심 구성 요소

  1. Project Context: 프로젝트의 목적과 핵심 기술 스택.
  2. Guiding Principles: 추구하는 아키텍처 철학 (예: “항상 Functional Programming 지향”).
  3. Code Style & Patterns: 변수 명명 규칙, 에러 핸들링 패턴 등.
  4. Useful Commands: 빌드, 테스트, 배포를 위한 핵심 스크립트 모음.

컨텍스트 오염 방지 팁

  • /memory 활용: 세션이 길어질 때 중요한 중간 결론을 /memory에 저장하여 핵심 컨텍스트만 보존합니다.
  • /compact 명령어: 불필요한 대화 기록을 압축하여 토큰 효율을 높이고 모델의 집중력을 유지합니다.
  • 세션 분리: 한 세션에서는 하나의 기능(Feature) 구현에만 집중하고, 완료 후에는 clear를 통해 새로운 컨텍스트로 시작하는 것이 좋습니다.

결론: 에이전트를 부리는 ‘엔지니어’의 자세

Claude Code는 단순한 챗봇이 아니라, 우리가 구축한 하네스(Harness) 안에서 동작하는 엔진입니다. 훌륭한 엔지니어는 AI가 코드를 잘 짜길 기도하는 것이 아니라, 잘 짤 수밖에 없는 환경(Spec, Plan, Hooks, Rules)을 설계합니다.

참고자료

1. 공식 문서 및 핵심 가이드

2. 하네스 엔지니어링 & 실무 워크플로우

3. 실무 팁 및 오픈소스 플러그인

4. 커뮤니티 인사이트

Leave a Comment

© 2026 Marketer • Built with GeneratePress
Privacy PolicyTermsContact