📑 이 챕터에서 다룰 내용
새 11·12장에서 5파일+와 5확장이 손에 들렸습니다. 그러나 5파일을 "매번 손으로 갱신"하면 운영자가 무너집니다. SPEC을 바꿨는데 PLAN·REVIEW·CLAUDE.md를 깜빡 → 6개월 후 5파일 사이 일관성 깨짐 → 동업자가 펼치면 "무엇이 진짜인지" 모르는 상태.
이 장은 "손 갱신 부담을 줄이는 자동화 흐름"을 다룹니다. git hook·CI·cron — 세 자동화 도구로 5파일 갱신을 절반 이하로 줄입니다.
사전 지식: 새 5~11장 5파일 작성 / git 기본 / Claude Code 헤드리스 모드
이 장의 목적: 5파일 자동 갱신 흐름 3개 (git hook·CI·cron) + 수동 vs 자동 비용 비교 + 함정 인지
완료 후 결과물: 5파일 갱신 부담 60% 감소 + 1년 누적 효과 약 30~50시간 절감
자동화 = "5파일이 일관성 있게 살아있도록" 시스템에게 일을 맡기는 것. 운영자가 매번 의식하면 5번에 1번은 깜빡합니다. 그 1번이 6개월 후 동업자에게 "왜 SPEC과 BUILD가 다르지"의 혼란을 만듭니다.
자동 갱신을 도입하기 전에 "어디에서 손 갱신 부담이 발생하는가"를 분리합니다.
| 발생 시점 | 손 갱신 작업 | 분당 부담 | 깜빡 빈도 |
|---|---|---|---|
| SPEC 변경 | PLAN·REVIEW·CLAUDE.md 영향 검토 | 30~60분 | 50% |
| BUILD 일자별 트레이스 | LogOnTable 1~3줄 작성 | 5분 | 30% |
| Phase 완료 | CLAUDE.md §10 Current State 갱신 | 10분 | 70% |
| 게이트 통과 | REVIEW.md 12건 결과 + git tag | 30분 | 40% |
1주일 누적 부담: 약 1.5~3시간 (작업 시간의 10~15%). 이 부담이 "자동화 가능 영역"입니다.
50% 깜빡은 "두 번 중 한 번은 안 한다"의 의미. 운영자의 의식 부족이 아니라 "인간의 한계"입니다. 그래서 자동화가 필요합니다.
도구 1: git hook (로컬 — commit 시점)
git이 commit·push 시점에 자동 실행하는 스크립트. 가장 가벼운 자동화입니다.
#!/bin/bash # SPEC.md가 변경됐으면 PLAN·REVIEW·CLAUDE.md 영향 검토 알림 if git diff --cached --name-only | grep -q "SPEC.md"; then echo "⚠️ SPEC.md 변경 감지. PLAN·REVIEW·CLAUDE.md 영향 검토 의식하세요." echo "다음 명령으로 자동 검토 가능:" echo " claude --print 'SPEC.md 변경에 따라 PLAN·REVIEW·CLAUDE.md 영향 1쪽 요약'" fi # BUILD.md 트레이스 누락 검증 (오늘 날짜 트레이스 있는지) TODAY=$(date +%Y-%m-%d) if ! grep -q "$TODAY" BUILD.md 2>/dev/null; then echo "💡 오늘($TODAY) BUILD.md 트레이스가 비어있습니다. (선택)" fi
적용 효과: SPEC 변경 깜빡 빈도 50% → 10%. 매 commit 시점에 알림.
도구 2: CI (GitHub Actions — push 시점)
push 시점에 GitHub Actions가 자동 실행. 5파일 일관성을 자동 검증합니다.
name: 5파일 일관성 검증
on:
push:
paths:
- "SPEC.md"
- "PLAN.md"
- "REVIEW.md"
- "BUILD.md"
- "CLAUDE.md"
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: SPEC ↔ PLAN 일관성 검증
run: |
SPEC_COUNT=$(grep -c "Phase 1 기능" SPEC.md || true)
PLAN_COUNT=$(grep -c "Phase 1 DoD" PLAN.md || true)
[ "$SPEC_COUNT" -eq "$PLAN_COUNT" ] || exit 1
- name: CLAUDE.md 200줄 이하 검증
run: |
LINES=$(wc -l < CLAUDE.md)
[ "$LINES" -le 200 ] || (echo "CLAUDE.md $LINES줄 (200 초과)" && exit 1)
- name: BUILD.md 최근 3일 트레이스 누락 알림
run: |
./scripts/check-build-trace.sh적용 효과: 5파일 사이 일관성 깨짐 자동 발견. 수동 검토 시간 30분 → 0분.
도구 3: cron (정기 — 매일·매주)
cron이 정기 시점에 자동 실행. 매일 BUILD.md 갱신 알림 + 매주 회고 자동 생성합니다.
# crontab -e # 매일 오후 9시 BUILD.md 트레이스 갱신 알림 (디스코드/텔레그램 봇) 0 21 * * * cd ~/projects/jupjup && ./scripts/build-trace-reminder.sh # 매주 일요일 오전 10시 5파일 회고 자동 생성 0 10 * * 0 cd ~/projects/jupjup && claude --print "5파일을 읽고 이번 주 변경 사항을 1쪽으로 회고" > weekly-review-$(date +%Y-W%V).md
적용 효과: 매일 BUILD.md 깜빡 빈도 30% → 5%. 매주 회고 자동 1쪽 생성.
가장 부담 큰 흐름이 "SPEC 변경의 영향 검토"입니다. 이걸 자동화하면 30~60분 → 5분으로 줄어듭니다.
흐름 — Claude Code 헤드리스 모드
#!/bin/bash if git diff HEAD~1 SPEC.md | head -1 | grep -q "diff"; then claude --print " SPEC.md 직전 commit과 비교해서 다음을 1쪽으로 답해줘: 1. 변경된 부분 1~2줄 요약 2. PLAN.md 영향 — 갱신 필요한 섹션 (있으면 1줄) 3. REVIEW.md 영향 — 갱신 필요한 체크 (있으면 1줄) 4. CLAUDE.md 영향 — 갱신 필요한 섹션 (있으면 1줄) 5. 권장 다음 작업 (1~3개) " > .spec-impact-review-$(date +%Y%m%d).md echo "✅ SPEC 영향 검토 완료. .spec-impact-review-*.md 펼치세요." fi
이 스크립트를 git hook 또는 CI에 박으면 SPEC 변경 시점에 자동 실행됩니다. 운영자는 5분 검토만 하면 됩니다.
Junho 적용 사례 — 줍줍 Day 17 SPEC 변경
[Day 17, 마이페이지 쿼리 변경 결정] 1. SPEC.md "마이페이지 정의" 섹션 변경 (1줄) 2. git commit → CI 자동 실행 3. .spec-impact-review-2026-XX-XX.md 자동 생성 4. 결과: - PLAN.md Day 17 DoD 영향 X - REVIEW.md G3 검증 영향 X - CLAUDE.md §10 Current State 영향 X - 권장: BUILD.md Day 17 트레이스에 변경 사유 1줄 박기 → 운영자는 5분 검토 + BUILD.md 1줄만 추가 (10분 소요) 기존 손 검토 30~60분 → 10분 (-66%)
BUILD.md 일자별 트레이스의 "매일 5분 손 작성" 부담을 줄이는 흐름입니다. git commit 메시지가 자동으로 BUILD.md에 누적되도록 만듭니다.
#!/bin/bash TODAY=$(date +%Y-%m-%d) COMMIT_MSG=$(git log -1 --pretty=%B) COMMIT_HASH=$(git log -1 --pretty=%h) # BUILD.md에 오늘 날짜 섹션이 없으면 추가 if ! grep -q "## $TODAY" BUILD.md; then echo "" >> BUILD.md echo "## $TODAY" >> BUILD.md echo "" >> BUILD.md fi # commit 메시지를 BUILD.md 오늘 섹션에 1줄 추가 echo "- [$COMMIT_HASH] $COMMIT_MSG" >> BUILD.md
효과: BUILD.md 트레이스의 "무엇을 했는가" 부분이 자동 누적됩니다. 운영자는 "왜 그 결정" 1~3줄만 추가하면 됩니다. 5분 → 1~2분.
"무엇"은 commit 메시지로 자동화 가능하지만 "왜"는 운영자만 알 수 있습니다. E4 LogOnTable의 핵심 가치는 "왜" 보존입니다. 자동화하면 가치가 사라집니다.
자동화는 "무엇" 부분만. "왜" 1~3줄은 매일 의식 — 자동화 불가.
자동화 도입 비용 vs 매일 절감 비용을 비교합니다.
도입 비용 (1회)
| 자동화 | 도입 시간 | 도입 후 매일 시간 |
|---|---|---|
| git hook (pre-commit) | 1시간 | 0분 (자동) |
| GitHub Actions CI | 2시간 | 0분 (자동) |
| cron (매일·매주) | 1시간 | 0분 (자동) |
| SPEC 영향 검토 스크립트 | 2시간 | 5분 검토 |
| BUILD.md 자동 누적 | 1시간 | 1~2분 (왜 추가) |
| 합계 | 7시간 (1회) | 6~7분/일 |
1주·1개월·1년 누적 비교
| 기간 | 수동 갱신 | 자동화 도입 후 | 절감 |
|---|---|---|---|
| 1주 | 1.5~3시간 | 0.5~1시간 | -1~2시간 |
| 1개월 | 6~12시간 | 2~4시간 | -4~8시간 |
| 1년 | 72~144시간 | 24~48시간 | -48~96시간 |
도입 비용 7시간 vs 1년 절감 48~96시간 = 약 7~14배 ROI.
자동화는 "이번 주에는 효과가 작아 보임"의 함정이 있습니다. 1주 1~2시간은 의식 부족으로 "그냥 손으로 하자"가 될 수 있습니다.
그러나 1년 누적 48~96시간 — 휴가 1~2주 분량입니다. 그 시간에 다른 프로젝트 시작·번아웃 회복·가족과 시간 — 모두 가능합니다.
자동화에는 함정이 있습니다. 이 4개를 알면 함정을 피할 수 있습니다.
함정 1: 자동 갱신 후 검토 X → 잘못된 SPEC이 깊이 묻힘
CI가 SPEC 변경을 "자동 통과"시키면 잘못된 SPEC이 깊이 묻힙니다. 6개월 후 "왜 이렇게 됐지"의 답을 못 찾는 상태입니다.
해결: 자동화는 "알림·생성·검증"까지. "의식적 검토"는 운영자가 매번. CI가 PASS여도 운영자가 5분 검토는 의무입니다.
함정 2: 자동 도구가 깨졌는데 모름 → 6개월 누적 깜빡
git hook이 깨졌는데 모르고 6개월. 그 6개월 동안 SPEC 변경 알림이 작동하지 않습니다.
해결: 매월 1회 30분 "자동화 작동 점검" 의식. (새 12장 자기 평가 흐름의 일부.)
함정 3: 자동화 커지면 자동화 자체가 부담
git hook 5개 + CI 워크플로우 10개 + cron 8개 = 자동화 자체 유지가 매주 1시간 부담. 자동화 ROI가 무너집니다.
해결: "꼭 필요한 자동화만" 5개 이하. 더 추가 시 "이게 필요한가" 검토.
함정 4: 자동화 = 의식 X → E4 LogOnTable 가치 사라짐
BUILD.md를 "commit 메시지 자동 누적만"으로 운영하면 "왜 그 결정" 1~3줄이 사라집니다. E4의 핵심 가치("왜 보존")가 사라집니다.
해결: 자동화는 "무엇" 부분만. "왜" 1~3줄은 매일 운영자 의식. (5분 → 1~2분으로 줄어들지만 0분은 불가합니다.)
줍줍 (Phase 1.0, 30일)
[Day 1 — 자동화 도입 7시간 (1회)] - git hook (pre-commit + post-commit) - GitHub Actions (5파일 일관성 검증) - cron (매일 21시 BUILD.md 알림 + 매주 일요일 회고 자동 생성) - SPEC 영향 검토 스크립트 - BUILD.md 자동 누적 [Day 1~28 — 매일 절감] - 손 갱신 부담: 매일 25분 → 7분 - 28일 누적 절감: 약 8.4시간 [Phase 1.0 30일 누적] - 도입 비용 7시간 - 절감 약 8.4시간 - 순 절감 +1.4시간 - ★ 누적 효과는 Phase 1.1·1.2 (60일+)에서 폭증
TSV (시리즈 약 15개월)
[시리즈 누적 자동화 효과] - 도입 비용 7시간 (Day 1) - 매일 절감 약 18분 - 약 15개월 (450일) 누적: 450 × 0.3h = 135시간 절감 - ★ 1인 운영자에게 "휴가 3.5주" 분량
자동화의 진짜 가치는 "매일 작아 보이는 절감의 누적"입니다. 1주 1~2시간이 1년 48~96시간이 됩니다. TSV 15개월 누적 135시간 절감 = 휴가 3.5주 분량이에요.
- 핵심 한 줄: 5파일 자동 갱신 = git hook + CI + cron 3개 도구. 도입 비용 7시간 vs 1년 절감 48~96시간 (ROI 7~14배)
- 손 갱신 부담 4 발생 시점: SPEC 변경 30~60분 (깜빡 50%) / BUILD 일자별 트레이스 5분 (깜빡 30%) / Phase 완료 CLAUDE.md 갱신 10분 (깜빡 70%) / 게이트 통과 REVIEW + tag 30분 (깜빡 40%)
- 3 자동화 도구: git hook (pre-commit·post-commit) — 1시간 도입 / GitHub Actions CI — 2시간 도입 / cron (매일·매주) — 1시간 도입
- SPEC 변경 영향 자동 검토: Claude Code 헤드리스 모드로 1쪽 요약 자동 생성. 운영자는 5분 검토만
- BUILD.md 자동 누적: git commit 메시지 → BUILD.md 오늘 섹션 자동 추가. "무엇" 자동, "왜" 1~3줄은 운영자 의식 (E4 가치 보존)
- 1년 누적 효과: 1주 -1~2시간 → 1년 -48~96시간 = 휴가 1~2주 분량
- 함정 4개: 자동 통과 → 잘못된 SPEC 묻힘 / 도구 깨졌는데 모름 / 자동화 자체 부담 (5개 이하 권장) / "왜" 자동화 → E4 가치 사라짐
- 다음 장: 새 14장 — WITH-CONDITIONS. 새 15장에서 WITH-CONDITIONS 깊이 다룸