13장 — 5파일 자동 갱신 흐름
CHAPTER 13
5파일 자동 갱신 흐름
git hook·CI·cron으로 갱신 부담 줄이기
📑 이 챕터에서 다룰 내용

새 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가 다르지"의 혼란을 만듭니다.

13-1 손 갱신 부담의 4 발생 시점 🔗

자동 갱신을 도입하기 전에 "어디에서 손 갱신 부담이 발생하는가"를 분리합니다.

발생 시점손 갱신 작업분당 부담깜빡 빈도
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 tag30분40%

1주일 누적 부담: 약 1.5~3시간 (작업 시간의 10~15%). 이 부담이 "자동화 가능 영역"입니다.

⚠️ "깜빡 빈도"의 의미

50% 깜빡은 "두 번 중 한 번은 안 한다"의 의미. 운영자의 의식 부족이 아니라 "인간의 한계"입니다. 그래서 자동화가 필요합니다.

13-2 자동화 도구 3개 — git hook·CI·cron 🔗

도구 1: git hook (로컬 — commit 시점)

git이 commit·push 시점에 자동 실행하는 스크립트. 가장 가벼운 자동화입니다.

💻 .git/hooks/pre-commit (실행 권한 부여 필수)
#!/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파일 일관성을 자동 검증합니다.

💻 .github/workflows/five-files-check.yml
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 설정 예시
# 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쪽 생성.

13-3 SPEC 변경 → PLAN·REVIEW·CLAUDE.md 자동 검토 🔗

가장 부담 큰 흐름이 "SPEC 변경의 영향 검토"입니다. 이걸 자동화하면 30~60분 → 5분으로 줄어듭니다.

흐름 — Claude Code 헤드리스 모드

💻 scripts/spec-impact-review.sh
#!/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 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%)
13-4 BUILD.md 자동 갱신 — git commit 메시지로 🔗

BUILD.md 일자별 트레이스의 "매일 5분 손 작성" 부담을 줄이는 흐름입니다. git commit 메시지가 자동으로 BUILD.md에 누적되도록 만듭니다.

💻 .git/hooks/post-commit
#!/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줄은 매일 의식 — 자동화 불가.

13-5 수동 vs 자동 비용 비교 — 1주·1개월·1년 🔗

자동화 도입 비용 vs 매일 절감 비용을 비교합니다.

도입 비용 (1회)

자동화도입 시간도입 후 매일 시간
git hook (pre-commit)1시간0분 (자동)
GitHub Actions CI2시간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주 1~2시간은 의식 부족으로 "그냥 손으로 하자"가 될 수 있습니다.

그러나 1년 누적 48~96시간 — 휴가 1~2주 분량입니다. 그 시간에 다른 프로젝트 시작·번아웃 회복·가족과 시간 — 모두 가능합니다.

13-6 자동 갱신의 함정 — 4개 🔗

자동화에는 함정이 있습니다. 이 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분은 불가합니다.)

13-7 Junho 적용 흐름 — 줍줍·TSV 둘 다 🔗

줍줍 (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개월)

💻 TSV 시리즈 누적 자동화 효과
[시리즈 누적 자동화 효과]
- 도입 비용 7시간 (Day 1)
- 매일 절감 약 18분
- 약 15개월 (450일) 누적: 450 × 0.3h = 135시간 절감
- ★ 1인 운영자에게 "휴가 3.5주" 분량
🎉 자동화의 진짜 가치

자동화의 진짜 가치는 "매일 작아 보이는 절감의 누적"입니다. 1주 1~2시간이 1년 48~96시간이 됩니다. TSV 15개월 누적 135시간 절감 = 휴가 3.5주 분량이에요.

📌 새 13장 정리
  • 핵심 한 줄: 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 깊이 다룸
🤖
1탄 학습 도우미
질문하기 OK
안녕하세요! 5파일 자동 갱신에 대해 무엇이든 물어보세요. 본문에서 찾아 답변해드릴게요. 👇