seal-commit: 변경 사항 리뷰 문서를 자동으로 생성하는 Git 커밋 기술

모든 개발자는 이 의식을 알고 있습니다: 코딩을 마치고, git status를 실행하고, 변경된 파일 목록을 멍하니 바라보다가, 커밋 메시지를 작성하고, 모든 것을 기억했기를 바라며 기도하는 과정 말입니다. 하지만 만약 당신의 AI 코딩 어시스턴트가 전체 커밋 워크플로우(workflow)를 안전하게, 그리고 완전한 문서화와 함께 처리할 수 있다면 어떨까요?

seal-commit은 git commit을 안전망, 스마트한 파일 선택, 자동 생성된 커밋 메시지, 그리고 동일한 커밋에 포함되는 이중 형식의 변경 사항 리뷰 문서(change review documents)로 감싸는 에이전트 기술(agent skill)입니다.

문제점

변경 사항을 커밋할 때, 일반적으로 세 가지 고충에 직면합니다:

1. 작업 손실에 대한 두려움 — 잘못된 git reset 또는 checkout 한 번에 커밋되지 않은 변경 사항이 사라질 수 있습니다.
2. 모호한 커밋 메시지 — "fix stuff" 또는 "update files" 같은 메시지는 미래의 자신에게 아무런 정보도 주지 못합니다.
3. 변경 사항 문서화 부재 — PR(Pull Request) 설명, 릴리스 노트(release notes), 코드 리뷰 컨텍스트(context)를 수동으로 작성해야 하며, 이는 종종 사후에 이루어집니다.

seal-commit이 하는 일

seal-commit은 커밋 워크플로우를 가이드되고 문서화된 프로세스로 변환하는 AI 에이전트 기술(Claude Code 및 호환 가능한 에이전트와 함께 작동)입니다:

1. Stash 기반 안전 스냅샷 (Stash-based safety snapshot) — 다른 무엇보다 먼저, 설명이 포함된 git stash save(타임스탬프 + 파일 개수 + 주요 파일 이름)를 생성한 다음, 즉시 git stash apply를 실행합니다. 당신의 작업은 항상 복구 가능합니다.
2. 번호 매겨진 파일 선택 — 모든 변경/추적되지 않은 파일(untracked files)을 번호와 함께 나열합니다. 사용자는 그저 "all", "1,3,5" 또는 "cancel"이라고 입력하기만 하면 됩니다.
3. Diff 분석 — 실제 코드 변경 사항을 읽습니다 (git diff를 통해 추적된 파일 및 파일 읽기를 통해 추적되지 않은 파일).
4. 자동 생성된 변경 사항 리뷰 문서 — human.html(사이드바, 카드, 대화형 체크리스트가 포함된 풍부한 시각적 문서)과 ai.md(LLM 컨텍스트를 위한 밀도 있고 구조화된 마크다운)를 모두 생성합니다.
5. 자동 생성된 Conventional Commit 메시지 — 사용자 입력 없이 type(scope): subject 형식과 3~5개의 세부 불렛 포인트로 포맷팅합니다.

이 모든 것이 하나의 커밋 안에 — 코드 변경 사항과 문서가 함께 이루어집니다.

안전 우선: 제한된 명령 허용 목록 (The Restricted Command Allowlist)

이것은 핵심적인 설계 결정입니다. seal-commit은 안전한 git 명령만 실행합니다:

허용됨 (Allowed)	차단됨 (Blocked, 안전을 위해)
git stash save/apply	git reset
...

stash 안전망은 기술(skill)이 이를 파괴할 수 있는 명령을 절대 실행하지 않기 때문에 결코 위험에 처하지 않습니다.

이중 형식 변경 사항 리뷰 (Dual-Format Change Review)

모든 커밋은 .change-review/<branch>-<date>/ 경로에 두 개의 문서를 생성합니다:

human.html — 사람을 위한 시각적 리뷰 (Visual Review for People)

다음 기능을 포함하는 독립적인 HTML 파일입니다:

• 스크롤 추적 기능이 포함된 고정 사이드바 네비게이션
• 링크된 참조가 포함된 히어로 헤더 (Hero header)
• 색상으로 구분된 모듈 카드 (파랑, 호박색, 에메랄드, 보라색)
• 변경 전/후 (Before/After) 코드 비교 패널
• 클릭 가능한 체크표시가 있는 대화형 테스트 체크리스트
• 반응형 레이아웃 (Responsive layout)

ai.md — LLM을 위한 구조화된 컨텍스트 (Structured Context for LLMs)

AI 컨텍스트 주입 (Context injection)에 최적화된 밀도 높은 마크다운 (Markdown) 파일입니다:

• 사실 위주, 불필요한 내용 없음
• 실제 코드 스니펫 (변경 전/후)
• 모든 식별자(Identifier)를 백틱(backticks)으로 감쌈
• 비어 있는 섹션은 완전히 생략

작동 방식 (How It Works)

/seal 또는 /commit 또는 "commit"
    ↓
Step 0: git stash save + apply  ← 안전망 (safety net)
...

설치 (Installation)

npx skills add conanttu/skills/seal-commit -g -y

또는 수동 설치:

git clone https://github.com/conanttu/skills.git
cd skills
ln -s $(pwd)/seal-commit ~/.claude/skills/seal-commit

사전 요구 사항 없음 — 모든 git 저장소에서 작동합니다.

사용법 (Usage)

그저 "commit"이라고 말하거나 /seal을 입력하세요. 기술(skill)이 변경된 파일 목록을 번호와 함께 나열하면, 사용자는 원하는 파일을 선택하기만 하면 되며 나머지는 기술이 모두 처리합니다.

📝 Changed files:
1. src/api/auth.ts (modified)
2. src/types/user.ts (modified)
...

문서 전용 모드 (Docs Only Mode)

커밋하지 않고 변경 사항 리뷰만 생성합니다:

/seal doc

Conventional Commits

커밋 메시지는 자동으로 생성됩니다:

feat(auth): add token refresh interceptor

- Add axios interceptor for automatic token refresh
...

핵심 설계 결정 (Key Design Decisions)

• stash + apply (pop이 아님) — 커밋이 실패하더라도 stash를 온전하게 유지합니다.
• Docs before commit (커밋 전 문서 생성) — 리뷰 문서가 동일한 커밋에 포함됩니다.
• Restricted commands (제한된 명령어) — reset, checkout 또는 restore를 허용하지 않습니다.
• Dual output (이중 출력) — 사람은 HTML로, LLM은 Markdown으로 확인합니다.

vs Manual Workflow (수동 워크플로우와 비교)

	Manual (수동)	seal-commit
Safety net (안전망)	없음	자동 stash 스냅샷
...

Learn More (더 알아보기)

• GitHub Repository
• seal-commit Documentation

여러분의 커밋 워크플로우는 어떤가요? 아래에 의견을 공유해 주세요!