워크플로우와 자동화 이해

이 장에서는 AI 하니스의 워크플로우 자동화에 대해 다룹니다. /sync 명령어, Git/GitHub PR, 훅(Hooks), CI/CD 기초, 그리고 dev-sync.ts의 작동 원리를 배워보겠습니다.

자동화란 무엇인가

모든 옷을 손빨래해야 한다고 상상해 보세요. 하나하나 문지르고, 헹구고, 짜야 합니다. 매주 몇 시간씩 걸릴 것입니다. 그런데 세탁기가 발명되었습니다. 옷을 넣고 버튼을 누르면 세탁기가 전체 과정을 알아서 처리합니다. 이것이 바로 자동화(Automation)입니다. 반복적인 수동 단계를 대신 실행해 주는 시스템을 두는 것입니다.

같은 원리가 소프트웨어 개발과 AI 에이전트 워크플로우에도 적용됩니다. 앞선 장에서 에이전트들이 협력해서 연구, 슬라이드 데크, 핸드북을 만드는 과정을 배웠습니다. 그런데 에이전트가 작업을 마친 이후에는 무슨 일이 일어날까요? 변경 사항은 어떻게 저장되고, 검증되고, 공유될까요? 바로 여기서 워크플로우 자동화가 필요합니다.

수동 vs 자동

자동화가 있을 때와 없을 때의 워크플로우를 비교해 보겠습니다.

세탁기 비유

/sync 명령어를 프로젝트의 세탁기라고 생각해 보세요. 작업 후 워크플로우의 각 단계(감사, 버전 업데이트, 커밋, 푸시, PR 생성)를 직접 실행하는 대신, 하나의 명령어만 실행하면 시스템이 전체 사이클을 처리합니다. "옷"(변경된 파일)을 넣고, 버튼(/sync)을 누르면 나머지는 시스템이 알아서 합니다.

이 비유는 더 확장할 수 있습니다. 세탁기에 여러 코스(섬세, 강력 세탁)가 있듯이, 자동화 파이프라인도 다양한 시나리오에 맞게 설정할 수 있습니다. 그리고 세탁기가 옷을 일관되게 세척해 주듯이, 자동화도 프로젝트를 일관되게 유지해 줍니다.

/sync 명령어 이해하기

/sync 명령어는 AI 하니스의 핵심 자동화 명령어입니다. 작업 후 워크플로우 전체를 단일 호출로 캡슐화합니다. 에이전트, 스킬, 스크립트 등 프로젝트 파일을 수정하는 작업을 마칠 때마다 /sync를 실행하여 작업을 올바르게 마무리합니다.

5단계 Sync 파이프라인

/sync를 실행하면 시스템이 5개 단계를 순차적으로 실행합니다. 각 단계는 이전 단계가 성공적으로 완료되어야 다음 단계로 넘어갑니다.

언제 /sync를 실행해야 할까

프로젝트 파일을 수정한 모든 작업 세션의 끝에서 /sync를 실행해야 합니다. 구체적으로 다음과 같은 경우입니다.

• 에이전트를 추가, 수정, 또는 중단(deprecate)한 후
• 스킬을 생성, 업데이트, 또는 제거한 후
• 스크립트를 변경하거나 SCRIPTS.md의 상태를 업데이트한 후
• 거버넌스 파일(AGENTS.md, CLAUDE.md, GEMINI.md, CODEX.md)을 수정한 후
• common-contract.json이나 템플릿 파일을 변경한 후

Git & GitHub PR

자동화 파이프라인이 어떻게 작동하는지 이해하려면 Git과 GitHub Pull Request의 기본 개념을 알아야 합니다. 이 두 가지가 감사 이후 sync 파이프라인의 모든 단계를 뒷받침하는 도구입니다.

Git 기초

Git은 프로젝트의 파일에 대한 모든 변경 사항을 추적하는 버전 관리 시스템입니다. 프로젝트의 상세한 일기장이라고 생각하면 됩니다. 변경 사항을 저장할 때마다 Git은 누가, 언제, 무엇을 변경했는지 기록합니다.

AI 하니스 워크플로우에서 만나게 될 필수 Git 명령어입니다.

# 변경된 파일 확인
git status

# 변경된 파일의 실제 차이점 보기
git diff

# 변경 사항을 "스테이징 영역"에 추가 (커밋 준비)
git add <filename>

# 스테이징된 변경 사항을 메시지와 함께 기록
git commit -m "type(scope): description"

# 커밋을 원격 저장소(GitHub)로 전송
git push

# 원격 저장소의 최신 변경 사항 다운로드
git pull

# 새 브랜치 생성 (병렬 작업 라인)
git checkout -b feature/my-new-feature

# 커밋 히스토리 보기
git log --oneline

GitHub 기초

GitHub은 Git 저장소를 호스팅하는 웹 플랫폼입니다. Git 위에 협업 기능을 추가합니다: 팀 접근 관리, 코드 리뷰 도구, 이슈 추적, Pull Request. AI 워크스페이스는 GitHub에 있으며, sync 파이프라인이 GitHub와 상호작용하여 변경 사항을 푸시하고 PR을 생성합니다.

Pull Request (PR)

Pull Request (PR)는 한 브랜치의 변경 사항을 다른 브랜치로 병합하자는 제안입니다. 협업 프로젝트에서 코드 리뷰의 표준 메커니즘입니다. 작동 방식은 다음과 같습니다.

훅(Hooks)

훅(Hook)은 특정 이벤트가 발생할 때 자동으로 실행되는 스크립트입니다. "hook"이라는 단어는 낚시에서 유래했습니다. 물고기가 지나가면 낚시바늘이 물고기를 낚듯이, 코드 훅은 이벤트를 낚아서 그에 응답하는 스크립트를 실행합니다.

훅의 작동 방식

AI 하니스에서 훅은 핵심 순간에 규칙을 강제하고 검사를 자동화하는 데 사용됩니다. 개발자가 수동으로 검사를 실행하도록 의존하는 대신, 훅은 관련 이벤트가 발생할 때마다 검사가 자동으로 실행되도록 보장합니다.

가장 일반적인 유형의 훅은 Git 훅으로, 특정 Git 작업 전후에 Git이 자동으로 실행하는 스크립트입니다.

# pre-commit  — 커밋이 완료되기 전에 실행
#               용도: 시크릿 검사, 린트(lint), 파일 포맷팅

# commit-msg   — 커밋 메시지가 작성된 후에 실행
#               용도: 커밋 메시지 형식 검증

# pre-push     — 원격 저장소에 푸시하기 전에 실행
#               용도: 테스트 실행, 빌드 통과 확인

# post-merge   — 브랜치가 병합된 후에 실행
#               용도: 의존성 설치, 락 파일 업데이트

# post-checkout — 브랜치가 전환된 후에 실행
#               용도: 설정 파일 재로드, 환경 초기화

경보 시스템 비유

훅을 건물의 경보 시스템이라고 생각해 보세요. 매일 밤 모든 문과 창문을 잠그는 것을 기억할 필요가 없습니다. 경보 시스템이 자동으로 모니터링합니다. 권한 없이 문이 열리면 경보가 즉시 울립니다. 마찬가지로 훅도 워크플로우를 자동으로 모니터링합니다.

AI 하니스에서는 도구 수준에서도 훅을 정의할 수 있습니다. 예를 들어 Claude Code 훅은 AI 에이전트가 파일을 수정하려고 할 때 스크립트를 트리거할 수 있어, Git 훅 이상의 추가 강제 레이어를 제공합니다.

쉽게 말해 도구 수준 훅은 AI 에이전트를 위한 자동 안전장치입니다. 에이전트가 파일을 고치려 하거나 다른 에이전트를 부르는 그 순간에 끼어들어, 문제가 커지기 전에 잡아 줍니다. 실제로 이 워크스페이스의 .claude/settings.json에는 아래와 같은 도구 훅이 등록되어 있습니다(2026-08-24 기준).

CI/CD 기초

CI/CD는 Continuous Integration / Continuous Delivery(지속적 통합 / 지속적 배포)의 약자입니다. 코드 변경 사항을 테스트하고 배포하는 과정을 자동화하는 실천 방법입니다. CI/CD는 소프트웨어 엔지니어링의 넓은 주제지만, 기본 개념을 이해하면 AI 하니스가 품질을 어떻게 유지하는지 파악하는 데 도움이 됩니다.

지속적 통합 (CI)

지속적 통합(Continuous Integration)은 누군가 변경 사항을 푸시할 때마다 자동으로 코드를 빌드하고 테스트하는 것을 의미합니다. 지정된 "테스트의 날"을 기다리는 대신, 모든 변경이 즉시 테스트됩니다. 이렇게 하면 버그와 문제를 수정하기 가장 쉬운 초기 단계에서 잡을 수 있습니다.

AI 하니스의 맥락에서 CI는 Pull Request가 생성되거나 업데이트될 때마다 감사 스크립트, 검증 검사, 테스트를 자동으로 실행하는 것을 의미합니다.

지속적 배포 (CD)

지속적 배포(Continuous Delivery)은 코드 변경 사항을 릴리스 준비 상태로 자동화하는 것을 의미합니다. 테스트를 통과한 후 시스템은 최소한의 수동 개입으로 변경 사항을 프로덕션에 배포할 수 있습니다. 핵심 단어는 "배달(delivery)"입니다. 변경 사항이 출하 준비되지만, 최종 릴리스는 여전히 사람이 승인합니다.

AI 하니스에서 CD는 PR이 승인되고 병합되면 업데이트된 워크스페이스가 모든 팀원과 변형 프로젝트에 자동으로 제공되는 것을 의미합니다.

GitHub Actions 예시

GitHub과 함께 가장 많이 사용되는 CI/CD 도구는 GitHub Actions입니다. 간단한 CI 워크플로우가 개념적으로 어떻게 보이는지 살펴보겠습니다.

# PR이 생성될 때 자동으로 실행
on: pull_request

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: bun install
      - run: bun scripts/audit.ts              # 워크스페이스 검증
      - run: bun scripts/validate-skills.ts    # 스킬 확인

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: gitleaks detect                   # 시크릿 스캔

dev-sync.ts의 작동 원리

scripts/dev-sync.ts 스크립트는 sync 파이프라인을 구동하는 TypeScript 구현체입니다. /sync 명령어의 엔진입니다. 내부적으로 무엇을 하는지 알아보겠습니다.

목적

dev-sync.ts는 3단계 상속 계층 구조에서 변경 사항을 동기화합니다. L0 워크스페이스 루트나 L1 공통 템플릿에서 파일을 수정하면 dev-sync.ts가 변경 사항이 모든 다운스트림 변형 프로젝트(L2)에 올바르게 전파되도록 합니다. L2 변형은 기본 구조를 L0과 L1에서 상속받기 때문에 이 동기화가 없으면 상위의 변경이 이를 의존하는 변형에 절대 도달하지 않습니다.

4단계 프로세스

dev-sync.ts 수동 실행

/sync가 전체 파이프라인을 자동으로 실행하지만, 더 많은 제어가 필요할 때 dev-sync.ts를 직접 실행할 수도 있습니다.

# sync 스크립트 직접 실행
bun scripts/dev-sync.ts

# 스크립트가 수행하는 작업:
# 1. L0 및 L1의 변경 사항 감지
# 2. 공통 계약에 대한 검증
# 3. 다운스트림 변형에 변경 사항 게시
# 4. 모든 프로젝트의 무결성 검증

# 도움말 및 사용 가능한 옵션 확인
bun scripts/dev-sync.ts --help

실습: 워크플로우 직접 체험하기

이제 처음부터 끝까지 현실적인 워크플로우를 직접 체험해 보면서 모든 것을 종합해 보겠습니다. 목표: 파일 변경을 하고, 커밋하고, /sync를 실행하여 전체 자동화 파이프라인을 완료하는 것입니다.

배후에서 일어나는 일

이 워크플로우를 따를 때 시스템이 각 단계에서 무엇을 하는지 살펴보겠습니다.