명세 기반 vs 인터랙티브: 상황별 Claude Code 생산성 운용 레시피

핵심 요약 (TL;DR)

두 가지 접근법을 상황에 맞게 쓰세요.

명세 기반(사전 설계): 복잡·장기·품질 중요 과제에 적합.
단계별 인터랙티브(바로 코딩): 작고 독립된 작업·백로그 정리에 매우 효율적.

CLAUDE.md(글로벌/프로젝트 가이드)는 “짧고 강력하게(≤100줄)” 유지.

금지/필수, TDD, 실패 시 3회 시도 제한, 품질 게이트만 선명하게.

검증·테스트는 사람이 책임.

AI 코드/테스트 전량 리뷰, 누락 테스트는 직접 추가하거나 AI에 생성 지시 후 재검토.

컨텍스트 로트(Context Rot) 방지:

작업을 작은 인크리먼트로 나눠 진행, 매 단계 끝에 계획/요약 문서 업데이트, 세션 리셋.

자동 품질 게이트(husky, lint-staged, commitlint, TDD-Guard)로 AI 오버스텝 차단.

“실패 테스트 1개만 허용 → 최소 구현 → 리팩토링” 파이프라인을 Git 훅으로 강제.

맞는 문제를 선택:

“대형 제품의 핵심 기능”보다 테스트·문서·보일러플레이트·E2E·마이그레이션 같은 정신 부담 낮은 백로그에서 ROI가 큽니다.

언제, 어떤 전략을 쓸까?

명세 기반(사전 설계)가 빛나는 경우

새 기능이 복잡/규모 큼/다수 모듈 영향/레거시와 결합되는 경우
품질·성능·보안 요구사항이 명확하고 검수 기준(테스트·수용조건)이 필요한 경우
예: 인보이스 CRUD + 권한, 키 데이터 마이그레이션, 사내 API 규약 준수 기능

단계별 인터랙티브가 더 효율적인 경우

독립적이고 작은 단위 백로그(테스트 추가, 정적 분석 교정, 문서화, 작은 리팩토링)
UI E2E 테스트(Playwright), 스크립트/툴링, 설정 자동화
예: 새 워크스페이스에서 Playwright 테스트 세팅, data-testid 보강, 문서 자동화

팁: 명세 기반이 항상 더 낫지 않습니다. 실제로는 문제 특성과 팀 역량, 시간 제약에 따라 전략을 혼합하세요.
복잡도↑ → 명세 강화, 단위↓/독립↑ → 인터랙티브 강화.

300x250

CLAUDE.md — “짧고 강력하게” (글로벌/프로젝트)

원칙: 100줄 이내, “금지/필수/테스트/TDD/3회 규칙/품질 게이트”만 남기기.
장황한 철학·모호한 미사여구는 잘 지켜지지 않습니다. 가드레일만 선명히!

미니멀 예시 (글로벌 공용, ~/.claude/CLAUDE.md)

# CLAUDE.md (Global)

## 원칙
- 작은 단위로 진행, 매 단계 컴파일+테스트 통과
- 기존 코드 패턴 학습 후 구현
- 명확성 > Cleverness, 조기 추상화 금지

## 프로세스
1) 계획(3~5단계로 쪼개기, IMPLEMENTATION_PLAN.md 작성/갱신)
2) TDD: 실패 테스트 → 최소 구현 → 리팩토링 → 커밋(이유 설명)
3) 3회 실패 시 중단하고 접근 재평가(무엇/왜 실패했는지 기록)

## 품질 게이트
- 전 테스트 통과, 린터 경고 0, 포매터 적용
- 커밋 메시지에 "왜" 포함, TODO는 이슈 번호와 함께
- `--no-verify` 금지, 테스트 비활성화 금지

## 테스트 지침
- 동작 중심, 결정론적, sleep 지양
- 테스트당 하나의 명확한 단언, 기존 유틸 재사용

## 오류 처리
- Fail Fast, 구체적 메시지, 예외 은폐 금지

## 결정 기준
1) 테스트 용이성 2) 6개월 후 가독성 3) 프로젝트 일관성 4) 단순성 5) 변경 용이성

프로젝트 전용 CLAUDE.md는 “맵 역할”

프로젝트 목적/범위/중요 명령만 최상위에 배치
상세 규칙/패턴/도구 사용법은 하위 폴더 문서로 분리
각 세션 종료 시 진행 현황/요약/다음 단계를 업데이트시켜 “준-장기 기억” 역할 수행

컨텍스트 로트(Context Rot) 최소화 루틴

작업은 20~90분 단위로 쪼개 진행
매 단계 끝나면 IMPLEMENTATION_PLAN.md와 프로젝트 CLAUDE.md를 갱신
세션 리셋 → 다음 단계 컨텍스트만 적재 (불필요한 히스토리 제거)
“오버스텝 방지 훅”을 코드/깃 훅으로 시스템화

자동 품질 게이트(필수 예시)

(1) package.json 스크립트

{
  "scripts": {
    "format": "prettier -w .",
    "lint": "eslint .",
    "test": "vitest run --reporter=dot",
    "test:watch": "vitest",
    "tdd:guard": "node scripts/tdd-guard.js"
  }
}

(2) Husky & lint-staged & commitlint

# 설치
npm i -D husky lint-staged @commitlint/{cli,config-conventional}
npx husky init

# .husky/pre-commit
cat > .husky/pre-commit <<'SH'
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
npm run format
npm run lint
npm run tdd:guard
npm test
SH
chmod +x .husky/pre-commit

# .husky/commit-msg
cat > .husky/commit-msg <<'SH'
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
npx --no-install commitlint --edit "$1"
SH
chmod +x .husky/commit-msg

# package.json (추가)
{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": ["eslint --fix", "prettier -w"],
    "*.{md,json,yml,yaml}": ["prettier -w"]
  },
  "commitlint": { "extends": ["@commitlint/config-conventional"] }
}

(3) TDD-Guard(단일 실패 테스트만 허용)

// scripts/tdd-guard.js
import { execSync } from "node:child_process";

try {
  execSync("vitest run --reporter=json --silent > .vitest.json", { stdio: "inherit" });
} catch (e) {
  // vitest run exits non-zero on failures; we'll parse file instead
}

import fs from "node:fs";
const data = JSON.parse(fs.readFileSync(".vitest.json", "utf8"));
const failed = data?.numFailedTests ?? 0;

// ▶ 실패 테스트 1개만 허용 (Red 단계 보장)
if (failed === 0) {
  console.error("[TDD-Guard] 실패 테스트가 없습니다. 우선 '실패하는 테스트'를 작성하세요.");
  process.exit(1);
}
if (failed > 1) {
  console.error(`[TDD-Guard] 실패 테스트가 ${failed}개입니다. 지금은 1개만 허용됩니다.`);
  process.exit(1);
}
console.log("[TDD-Guard] OK: 실패 테스트 1개 감지. 최소 구현으로 Green 단계로 진행하세요.");

효과: 테스트를 한꺼번에 작성하거나 대규모 변경을 시도하는 AI 습관을 차단 → “작게 실패→작게 수정→리팩토링” 리듬을 강제

에이전트 프롬프트 레시피 (복붙용)

세션 시작(명세 기반)

“이 프로젝트의 목적/범위/제약은 다음과 같습니다: …
우선 IMPLEMENTATION_PLAN.md에 3~5단계 계획을 작성하고, 각 단계에 성공 기준·테스트를 포함하세요. 끝나면 요약만 출력하세요.”

세션 시작(인터랙티브)

“현재 목표는 X입니다. 우선 코드베이스를 빠르게 스캔하고, 영향 범위를 요약하세요. 그 다음 단계1만 수행하고 PR 가능한 최소 변경만 제안하세요. 테스트는 실패 1개만 만들고 시작하세요.”

코드 리뷰 요청

“방금 생성한 커밋에 대해 코드 리뷰(구조/테스트/성능/에러 처리/보안)를 해주세요. ‘중요도 상·중·하’로 지적하고, 각 항목에 구체적 수정 패치를 제시하세요.”

계획/요약 갱신

“완료한 단계의 상태를 업데이트하고, 다음 단계에 필요한 컨텍스트(파일 경로, 주의점, 테스트 포인트)를 3~5줄로 요약하여 프로젝트 CLAUDE.md 하단에 덧붙이세요.”

막혔을 때(3회 규칙)

“동일 이슈로 3회 실패했습니다. 실패 시도/오류/원인을 요약하고, 다른 접근 2~3가지 제안 및 예상 리스크/테스트를 적은 뒤, 가장 단순한 안으로 미세 단계 계획을 재작성하세요.”

검증·테스트·리뷰 — 실무 체크리스트

사람이 최종 책임: PR에 이름이 올라가면 검토·테스트 품질은 본인 책임입니다.
테스트 추가/보강: 경계·에러·성능·보안 케이스를 따로 요구하세요.
E2E(UI) 자동화: Playwright 등으로 사용자 시나리오 중심 테스트(동기화·결정론적).
리팩토링 전: 테스트 보호망을 먼저 강화 후 변경.

보안·품질 관점 가이드

“AI 코드 품질 ↑ = 공격면 축소”를 목표로 기본 체계를 자동화하세요.

비밀 유출 방지

리포지토리/커밋 훅에 비밀 스캐너

# 예: Gitleaks
brew install gitleaks || go install github.com/gitleaks/gitleaks/v8@latest
gitleaks detect -v

프롬프트에 민감정보 예시 금지 명시 (키/토큰/고객데이터)

SCA(오픈소스 취약점)

# 예: OSV-Scanner
brew install osv-scanner || go install github.com/google/osv-scanner/cmd/osv-scanner@latest
osv-scanner --lockfile=package-lock.json

SAST(정적 분석)

# 예: Semgrep
pipx install semgrep
semgrep ci --config p/ci

SBOM & 라이선스

# SBOM 생성
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
syft dir:. -o spdx-json > sbom.spdx.json

빌드·배포 체인

잠금(pinning), 재현 가능한 빌드, 서명(예: Sigstore/Cosign) 고려
CI에서 테스트/스캔 실패 시 배포 차단

PR 템플릿에 보안 체크박스 포함

비밀/키가 노출되지 않았습니다.

SCA/SAST/SBOM 검사 결과를 첨부했습니다.

로그/에러에 민감정보가 포함되지 않습니다.

실패 패턴과 대응

오버스텝 루프: 한 번에 너무 많은 변경 → TDD-Guard + 작은 단계로 강제
명세 미스/추측 구현: 금지/필수·수용조건을 굵고 짧게 명시
테스트 부실: 경계/에러/동시성/성능·보안 케이스 체크리스트화
컨텍스트 상실: 단계 종료마다 요약·계획 갱신, 세션 리셋로 재시작
도메인 난이도↑: 전문 지식 과제는 과감히 제외하고, 백로그형 작업으로 전환

사양 문서 샘플(복붙 후 바로 사용)

(A) IMPLEMENTATION_PLAN.md (템플릿)

# IMPLEMENTATION_PLAN

## 단계 1: 인보이스 목록 조회(읽기 전용)
- 목표: /invoices 페이지에서 페이징+필터로 목록 표시
- 성공 기준: 200 OK, 빈/대량/경계 데이터 시 UI 정상, 쿼리 파라미터 유지
- 테스트: API 계약 테스트, UI E2E(목록/검색/페이징), 성능(1000건)
- 상태: Not Started

## 단계 2: 단건 조회/생성
- 목표: 상세 패널 + 생성 모달 (필수 필드 검증)
- 성공 기준: 400 검증 실패 시 명확 메시지, 201 생성 후 목록 반영
- 테스트: 단위(검증), API 계약, E2E(생성 흐름)
- 상태: Not Started

## 단계 3: 수정/삭제 + 권한
- 목표: 역할별 버튼 표시/비표시, 감사 로깅
- 성공 기준: 권한 없음 403, 삭제 복구 불가 안내
- 테스트: 권한 케이스, 로깅 어서션, E2E(수정/삭제)
- 상태: Not Started

(B) “인보이스 CRUD 페이지” 요구사항 요약

# SPEC: Invoices CRUD

## 목적/범위
- 재무팀용 인보이스 관리 UI (목록/보기/생성/수정/삭제)
- 역할: admin, editor, viewer (RBAC)

## 데이터 모델(요약)
- Invoice { id, number, customer, amount, status[Draft/Paid/Overdue], issuedAt, dueAt }

## API 계약(예시)
- GET /api/invoices?page&size&status&query
- POST /api/invoices (검증: number unique, amount>0, dueAt>=issuedAt)
- PUT /api/invoices/:id
- DELETE /api/invoices/:id

## 수용 기준(발췌)
- 필터·페이징 상태가 URL에 반영/복원
- 403 시 UI에 권한 부족 안내
- 삭제는 확인 모달 + 되돌릴 수 없음 명시

(C) “Playwright E2E 도입” 작업 지시서(축약)

# SPEC: Playwright E2E Bootstrap

## 목표
- 핵심 사용자 시나리오 3개(로그인, 인보이스 생성, 권한 차단) 자동화

## 해야 할 일
1) 새 워크스페이스 초기화, report/trace 저장
2) data-testid를 UI에 보강(PR1)
3) 시나리오별 테스트 파일 작성(PR2~PR4)
4) CI 연동(병렬/리트라이/flake 감지)

## 가이드
- sleep 금지(대신 expect, locator.waitFor)
- 테스트명은 시나리오를 그대로 설명

비용·운영 최적화(간단 전략)

워크플로 고정 후 다운스케일

초반엔 품질 높은 모델로 패턴/표준/보일러 정립 → 이후 저렴 모델로 반복 작업
프롬프트 템플릿화·예시 축소·컨텍스트 최소화로 토큰 절감

전략적 캐시/결과 재사용

생성물(테스트/유틸/문서) 재활용 → 동일 유형 작업에 재적용

파인튜닝/Distillation

반복되는 도메인 패턴이 명확해지면, 사내 템플릿+룰 기반으로 가벼운 모델 활용

구독/도구 가성비는 사용 빈도·자동화 범위·팀 규모에 좌우됩니다.
“매일 반복 작업을 줄이는 자동화”에 실사용한다면 비용 대비 효과가 커집니다.

실전 운영 팁(당신의 경험을 체계화)

웹 콘솔에서 아이데이션 → CLAUDE.md 1차 버전 생성
세션마다 글로벌+프로젝트 CLAUDE.md 읽고 시작
진행 중 요약/계획/코드 네비 업데이트를 Claude에게 지시
일회성/프로토타입은 자유롭게, 핵심/장기 코드는 엄격하게
여러 계정 병행 시 환경변수로 스위칭
alias claude-personal='CLAUDE_CONFIG_DIR=~/.claude-personal claude'

무엇을 CLAUDE.md에 넣고, 무엇을 뺄까?

넣기: “금지/필수”, 테스트/TDD 규칙, 3회 룰, 품질 게이트, 핵심 명령
넣기: 현재 프로젝트의 목적/지도(맵), 폴더 구조 힌트, 실행·빌드·테스트 명령
빼기: 모호한 미학/슬로건, 장문의 철학, 중복 규칙, 도구 상식 설명

최종 체크리스트

문제 유형에 맞는 전략 선택(명세 vs 인터랙티브)
CLAUDE.md ≤100줄, 금지/필수/테스트/3회 규칙/품질 게이트
IMPLEMENTATION_PLAN.md 3~5단계로 쪼개고 “성공 기준/테스트” 포함
TDD-Guard + husky + lint-staged + commitlint 세팅
각 단계 종료 시 요약·계획 갱신 + 세션 리셋
사람 리뷰 필수(코드+테스트), 누락 테스트 추가
SCA/SAST/SBOM/Secret 스캔 CI에 내장
오버스텝/로트 발생 시 단위 축소 + 계획 재작성

당신의 경험이 보여주듯, 명확한 단계 설계와 작은 단위의 엄격한 사이클만 잘 지키면 Claude Code는 시간을 단축하고 싫증 나는 백로그를 날로 처리해줍니다. 반대로 복잡·핵심 기능은 사람이 설계/리뷰/리팩토링으로 골격을 먼저 세우고, 그 다음 AI에게 메꾸기와 반복작업을 맡기면 생산성과 품질을 동시에 잡을 수 있습니다.

728x90

그리드형(광고전용)

저작자표시 비영리 동일조건 (새창열림)

pages.kr 날으는물고기 <º)))><

명세 기반 vs 인터랙티브: 상황별 Claude Code 생산성 운용 레시피

명세 기반 vs 인터랙티브: 상황별 Claude Code 생산성 운용 레시피

핵심 요약 (TL;DR)

언제, 어떤 전략을 쓸까?

CLAUDE.md — “짧고 강력하게” (글로벌/프로젝트)

미니멀 예시 (글로벌 공용, ~/.claude/CLAUDE.md)

프로젝트 전용 CLAUDE.md는 “맵 역할”

컨텍스트 로트(Context Rot) 최소화 루틴

자동 품질 게이트(필수 예시)

(1) package.json 스크립트

(2) Husky & lint-staged & commitlint

(3) TDD-Guard(단일 실패 테스트만 허용)

에이전트 프롬프트 레시피 (복붙용)

세션 시작(명세 기반)

세션 시작(인터랙티브)

코드 리뷰 요청

계획/요약 갱신

막혔을 때(3회 규칙)

검증·테스트·리뷰 — 실무 체크리스트

보안·품질 관점 가이드

실패 패턴과 대응

사양 문서 샘플(복붙 후 바로 사용)

(A) IMPLEMENTATION_PLAN.md (템플릿)

(B) “인보이스 CRUD 페이지” 요구사항 요약

(C) “Playwright E2E 도입” 작업 지시서(축약)

비용·운영 최적화(간단 전략)

실전 운영 팁(당신의 경험을 체계화)

무엇을 CLAUDE.md에 넣고, 무엇을 뺄까?

최종 체크리스트

댓글

티스토리툴바

명세 기반 vs 인터랙티브: 상황별 Claude Code 생산성 운용 레시피

명세 기반 vs 인터랙티브: 상황별 Claude Code 생산성 운용 레시피

핵심 요약 (TL;DR)

언제, 어떤 전략을 쓸까?

CLAUDE.md — “짧고 강력하게” (글로벌/프로젝트)

미니멀 예시 (글로벌 공용, ~/.claude/CLAUDE.md)

프로젝트 전용 CLAUDE.md는 “맵 역할”

컨텍스트 로트(Context Rot) 최소화 루틴

자동 품질 게이트(필수 예시)

(1) package.json 스크립트

(2) Husky & lint-staged & commitlint

(3) TDD-Guard(단일 실패 테스트만 허용)

에이전트 프롬프트 레시피 (복붙용)

세션 시작(명세 기반)

세션 시작(인터랙티브)

코드 리뷰 요청

계획/요약 갱신

막혔을 때(3회 규칙)

검증·테스트·리뷰 — 실무 체크리스트

보안·품질 관점 가이드

실패 패턴과 대응

사양 문서 샘플(복붙 후 바로 사용)

(A) IMPLEMENTATION_PLAN.md (템플릿)

(B) “인보이스 CRUD 페이지” 요구사항 요약

(C) “Playwright E2E 도입” 작업 지시서(축약)

비용·운영 최적화(간단 전략)

실전 운영 팁(당신의 경험을 체계화)

무엇을 CLAUDE.md에 넣고, 무엇을 뺄까?

최종 체크리스트

관련글

댓글

티스토리툴바