AI 작업 버전 관리
AI와 반복 작업하는 사람들은 좋은 버전을 잃습니다. 재생성 시 덮어쓰기, 실행 취소가 너무 멀리 가거나, 대화 흐름이 흐트러지기 때문입니다. 이 스킬은 모든 변경을 번호가 매겨진 버전으로 만들어 사용자가 삭제할 때까지 보존하므로, 언제든지 이전 상태를 보고, 비교하고, 되돌릴 수 있습니다.
세 가지 규칙
- 모든 변경이 버전을 얻습니다. 파일을 변경하는 사용자 요청 하나가 하나의 버전이며, 해당 턴이 끝날 때, 응답 전에 저장됩니다. 파일 편집별이 아닌 요청별로 저장하면 이력을 읽기 쉽게 유지할 수 있습니다.
- 복구해도 버전을 삭제하지 않습니다. 스크립트만
.ai-versions/에 씁니다. 정리 요청이 와도 그 안의 내용을 편집, 이동, 삭제하지 마세요. 대신 사용자에게backup을 안내하세요. - 복구는 새로운 버전입니다. 스크립트로 복구하세요. 기억에 의존해 이전 작업을 재구성하지 마세요. 복구는 새 버전으로 저장되므로, 그 역시 실행 취소할 수 있습니다.
스크립트가 모든 버전 번호를 결정합니다. 절대 추측하지 말고, 스크립트가 출력한 번호를 보고하세요.
프로젝트별 모드 선택
- 명령어 실행 및 파일 편집 가능 (Claude Code, Cursor, Codex, Windsurf, Copilot, Gemini CLI, Replit Agent, claude.ai 코드 실행 포함): 아래 파일 모드를 사용하세요.
- 프로젝트에
.github/workflows/ai-versions.yml이 있음: GitHub 버전 레이어를 사용합니다.init을 실행하지 마세요. 대신, 모든 변경 시.ai-versions/pending.json을 덮어쓰고, 복구 시.ai-versions/restore.json을 작성하세요. 둘 다 assets/rules/github-layer-rules.md에 설명되어 있습니다. - 명령어 실행 불가 (일반 채팅): references/chat-mode.md를 따르세요.
- 사용자가 Lovable, Bolt, v0 (Bolt와 v0는 베타: 아직 라이브 테스트 안 됨), 또는 Figma Make로 작업하고 버전 관리 방법을 묻는다면: references/app-builders.md를 읽으세요.
파일 모드
스크립트는 이 스킬 폴더(이 SKILL.md를 포함하는 폴더) 안의 scripts/aiv.py입니다. 전체 경로로 호출하고 --root로 프로젝트를 지정하세요:
python3 "<이 스킬 폴더>/scripts/aiv.py" --root "<프로젝트 폴더>" <명령어>
# Windows: python3 대신 py 사용
init 후, 각 프로젝트에도 자체 복사본이 생기므로 프로젝트 폴더에서 python3 .ai-versions/aiv.py <명령어>도 동일하게 작동합니다. 아래에서 aiv는 둘 중 아무 형태나 의미합니다. Python이 설치되지 않은 경우, 사용자에게 필요하다고 알리고(python.org) Python이 설치될 때까지 채팅 모드를 사용하세요.
시작
.ai-versions/가 없는 프로젝트에서 첫 편집 전에 init을 실행하세요. 현재 파일을 v1.0.0으로 저장하여 사용자가 항상 작업 전 상태로 되돌아갈 수 있게 합니다.
폴더에 프로젝트 외의 다른 것(샌드박스, 홈 폴더, 다운로드 폴더 등)이 있다면 범위를 지정하세요: init --only poster.html assets/. init은 5,000개 이상의 파일이 있는 폴더를 거부합니다. 이는 일반적으로 잘못된 폴더를 의미하기 때문입니다.
모든 변경 후
aiv save --bump minor --summary "3가지 요금제가 있는 가격 섹션 추가" \
--reason "새 섹션; 레이아웃 및 스타일 변경 없음" --prompt "3가지 요금제로 가격 추가"
--bump | 사용자에게 표시 | 시기 |
|---|---|---|
patch | 작은 조정 | 동일 기능, 약간의 조정: 텍스트, 색상, 간격, 크기, 작은 수정 |
minor | 새 기능 | 새로운 것, 동일 방향: 섹션, 페이지, 컴포넌트, 기능 |
major | 큰 변경 | 방향 변경: 리디자인, 새 레이아웃, 새 스타일 시스템, 기능 제거 |
여러 변경이 있는 하나의 요청은 가장 높은 수준을 사용합니다. 두 수준 사이에서 확실하지 않으면 더 낮은 수준을 선택하고 --reason에 그 이유를 명시하세요. 예외 사항(문서, 리팩터링, 콘텐츠 업데이트)은 references/bump-levels.md에 있습니다.
--summary는 개발자가 아닌 사용자를 위해 작성하세요: "Hero.tsx 업데이트"가 아닌 "히어로 이미지 크게 만들기". --prompt에는 사용자의 요청을 한 줄로 줄여 넣으세요.
그런 다음 응답을 한 줄로 끝내세요, 예: Saved v1.3.0 (New feature): 3가지 요금제가 있는 가격 섹션 추가.
save가 파일이 이전 버전과 정확히 일치한다고 알리면, 해당 버전으로 돌아가는 것으로 저장을 기록합니다. 사용자에게 그렇게 되었다고 알리세요.
사용자가 요청할 때
| 사용자 말 | 실행 | 이후 |
|---|---|---|
| "버전 보여줘", "기록" | list | 짧은 표를 보여주세요. 시각적 타임라인을 위해 view를 실행하고 작성된 HTML 파일을 공유하세요. |
| "v1.3.0에서 뭐가 바뀌었어?" | diff v1.3.0^ v1.3.0 | 평이한 말로 설명하세요. vX^는 vX 이전 버전을 의미합니다. |
| "v1.2와 v2.0 비교해줘" | diff v1.2.0 v2.0.0 --stat, 그 다음 세부사항을 위해 --stat 없이 | 무엇이 바뀌었고, 좋아졌고, 나빠졌는지 말하세요. 작업을 렌더링할 수 있다면(HTML, 이미지), 둘을 나란히 보여주세요. |
| "v1.2.0으로 돌아가", "실행 취소" | restore v1.2.0 또는 restore prev (실행 취소) | 그런 다음 아래 단계를 수행하세요. |
| "예전 헤더만 가져와", "예전 디자인은 유지하고 새 텍스트만" | restore v1.2.0 --path <파일> | 해당 파일만 변경되며, 작은 조정으로 저장됩니다. |
| "v1.2.0에서 다른 방향 시도" | restore v1.2.0 | 그런 다음 새 변경을 하고 평소처럼 저장하세요. |
| "현재 버전 뭐야?", "저장 안 된 거 있어?" | status | |
| "v1.2.0을 파일로 줘" | export v1.2.0 --out v1.2.0.zip | |
| "다른 채팅이나 도구에서 계속" | backup --out history.zip | 새 위치에서: import history.zip. |
사용자가 버전을 모호하게 말할 때 ("그 파란 거", "리디자인 전에"), list를 실행하고 요약과 일치시키세요. 두 버전이 맞으면 어느 것인지 물어보세요.
복구 후
전체 복구는 프로젝트의 모든 파일을 원래대로 되돌립니다. 여기에는 사용자가 작업의 일부로 생각하지 않을 수 있는 파일(예: 노트, 데이터)도 포함됩니다. 어떤 파일이 변경되었는지 사용자에게 알리세요(스크립트가 나열합니다). 저장되지 않은 작업을 먼저 저장했다면, 어떤 버전이 그것을 보유하고 있는지 말하고 restore <해당 버전> --path <파일>로 특정 파일을 가져올 수 있다고 제안하세요. 요청이 프로젝트의 일부만 명확히 대상으로 할 때 ("예전 색상"), 처음부터 --path를 사용하세요.
handoff <복구한 버전>을 실행하고 그 출력을 다음 변경 전에 현재 진실로 취급하세요. 해당 버전으로 이끈 결정만 나열하고 폐기된 결정의 이름을 지정하여, 버려진 방향의 지침이 다시 스며들지 않도록 합니다. 대화가 길면 새 채팅에서 계속할 것을 제안하고 사용자에게 거기에 붙여넣을 handoff 텍스트를 제공하세요.
저장 누락을 위한 안전망
Claude Code 또는 Cursor에서 프로젝트당 한 번 다음을 제안하세요: install-hooks claude-code 또는 install-hooks cursor. 완료 시 잊어버린 변경사항을 작은 조정으로 저장하는 훅을 추가합니다. 사용자가 동의한 후에만 설치하세요. 도구 설정에 쓰기 때문입니다.
버전에 대해 말하기
사용자의 언어를 사용하세요: 작은 조정, 새 기능, 큰 변경, 되돌아감. 커밋, .ai-versions/ 내 파일, 해시가 아닌 버전 번호를 언급하세요. 도구별 참고 사항(claude.ai, Replit, Windows)은 references/tools.md에 있습니다.
사용자가 되돌아갈 때 파일만 돌아온다는 점을 한 번 상기시키세요: 데이터베이스 행 및 기타 라이브 데이터는 그대로 유지됩니다.
모든 명령어
| 명령어 | 기능 |
|---|---|
init [--only PATH...] | 히스토리 시작 및 v1.0.0 저장 |
save --bump B --summary S [--reason R] [--prompt P] | 현재 파일을 새 버전으로 저장 |
status | 현재 버전 및 저장되지 않은 변경사항 |
list [--all] [--json] | 버전 목록 (최신순) |
show V | 한 버전의 상세 정보 및 변경된 파일 |
diff [A] [B] [--stat] [--path P...] | 인수 없음: 저장되지 않은 변경사항. 하나: A에서 최신까지. 둘: A에서 B까지 |
restore V [--path P...] [--note N] | 되돌아가기 (전체 파일 또는 일부만); 저장되지 않은 작업을 먼저 저장한 후, 복구를 새 버전으로 저장 |
handoff [V] | V에서 계속하기 위한 깨끗한 컨텍스트 |
view [--out FILE] | 모든 버전의 HTML 타임라인 |
export V --out DIR_or_ZIP | 한 버전의 파일 |
backup --out FILE.zip / import FILE.zip | 전체 히스토리 이동 |
install-hooks claude-code|cursor | AI가 잊어버린 것 자동 저장 |
setup-github [--with-pill] | 앱 빌더 저장소에 GitHub 레이어 추가 |
doctor | 히스토리에서 누락된 부분 확인 |
버전은 v1.2.0, 1.2.0, latest, prev, v1.2.0^으로 작성할 수 있습니다.