AIDive

영상 팩

Git에서 AI 스펙과 플랜 관리하기: 다섯 가지 규칙, drift gate, 출처, 체크리스트

읽는 데 11분

TL;DR

  • AI가 작성한 스펙과 플랜은 커밋하세요. 모든 도구가 기본값으로 이미 그렇게 합니다. 남은 문제는 거버넌스입니다.
  • 스쿼드마다 CODEOWNERS 한 줄이 걸린 폴더를 하나씩 두세요. 그러면 스펙이 바뀔 때 코드 오너에게 리뷰가 요청됩니다.
  • 공유 스펙마다 ADR 스타일 헤더를 붙이세요: status, superseded-by, owner, touched paths, review date. accepted 상태의 스펙을 새 결정으로 덮어쓰지 마세요.
  • CI에 drift gate를 두세요. accepted 스펙이 언급한 경로가 더 이상 존재하지 않으면 빌드를 실패시킵니다.
  • 출력 경로는 CLAUDE.md에 굵은 명령문 한 줄로 바꾸고, 개인 플랜은 CLAUDE.local.md와 .git/info/exclude에 두고, 작성은 main이 아니라 브랜치에서 하세요.
  • 스쿼드 경계를 넘는 작업이나 90일 뒤에도 다시 읽힐 작업만 스펙으로 쓰세요. 스펙 주도 작업은 시간이 약 2배, 토큰이 약 3배 듭니다.

출처가 말하는 것

기본값: 모두가 커밋한다

Superpowers writing-plans 스킬은 플랜을 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md에 저장하고, 그 아래에 플랜 위치에 대한 사용자 설정이 이 기본값을 덮어쓴다는 한 줄을 둡니다 s1. brainstorming 스킬은 검증된 설계를 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md에 쓰고 "Commit the design document to git"으로 끝납니다 s2. Spec Kit은 specs/[branch-name]/ 아래에 spec.md, plan.md, tasks.md를 두고 001, 002처럼 번호를 매기며, memory/constitution.md에 constitution을 둡니다 s6. Kiro는 기능마다 폴더 하나씩 .kiro/specs/를 유지하고, 팀이 "collaborate with team members on different features simultaneously"하도록 권합니다 s8. Anthropic의 플레이북은 분명합니다: "Every stage commits an artifact the next stage can read", "Commit the approved plan as plan.md", "When implementation departs from the plan, update plan.md in the same commit" s5.

이 문서들 중 어느 것도 커밋된 스펙의 주인이 누구인지, 언제 더 이상 사실이 아니게 되는지는 말하지 않습니다. 문서화된 세 가지 실패는 바로 그 빈틈에서 일어납니다.

실패 1: 공개 유출

2026-06-05에 열린 이슈 1690은 기본 위치인 docs/superpowers/가 Sphinx와 Read the Docs를 통해 내부 플랜을 공개 문서로 유출할 수 있다고 보고합니다 s15. 영향을 받은 프로젝트는 별 273개의 Python 라이브러리 okama였습니다. 수정 커밋은 플랜 5개와 스펙 3개를 다시 추가하고 .gitignore 한 줄을 지웠으며, 메시지는 "track superpowers plans/specs in git, excluded from the Sphinx build"입니다 s21. docs/conf.py의 84번째 줄에는 이제 exclude_patterns = ["_build", "Thumbs.db", "superpowers"]가 있습니다 s22. 지금 이 폴더에는 플랜 8개와 스펙 6개가 있습니다 s15. 팀은 관행을 유지하고 빌드를 고쳤습니다.

실패 2: main 위의 플랜

2026-04-22에 열려 아직 열려 있는 이슈 1246은 개발 브랜치가 생기기도 전에 왜 플랜이 커밋되는지 묻습니다. 한 사용자는 "I'm getting 10 to 15 commits"라고 쓰고, 다른 사용자는 "Yes please, no plans and specs on main branch!"라고 씁니다 s16. 플러그인은 브랜치 규칙을 강제하지 않습니다. 아래 체크리스트가 대신 강제합니다.

실패 3: 모델이 건너뛰는 오버라이드

이슈 337은 2026-03-10에 닫혔고, 메인테이너는 v5.0부터 플러그인이 자체 기본값보다 프로젝트의 CLAUDE.md를 우선한다고 적었습니다. 예시 줄은 "Save plans to ~/.superpowers/plans/ instead of docs/plans/"입니다 s17. v5.0.6의 이슈 939는 그 한계를 보여줍니다. CLAUDE.md의 "Output Paths" 표가 무시되었고 스펙은 계속 docs/superpowers/specs/에 저장되었습니다. 효과가 있었던 우회책은 표 아래에 굵은 명령문 한 줄을 두는 것입니다: design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. 지시문 순서를 바꾼 풀 리퀘스트 1020은 병합되지 않고 닫혔습니다 s19. 오버라이드는 설정이 아니라 프롬프트입니다. 플러그인 릴리스마다 다시 확인하세요. 플러그인 자체의 임시 파일은 이슈 1780이 v6.0.3에서 닫혔고, *가 들어 있는 자체 .gitignore를 만드는 스스로 무시되는 .superpowers/sdd/ 폴더가 그 답입니다 s20.

개인용과 공유용

Claude Code는 둘을 나눠 문서화합니다: "For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed" s3. 디렉터리별 CLAUDE.md 파일은 필요할 때 로드되며, "Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file"이고, 모노레포에서는 claudeMdExcludes 설정으로 다른 팀의 파일을 숨길 수 있습니다 s4. Git에는 세 겹의 ignore 계층이 있습니다. $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude, .gitignore입니다 s24. 가운데 것은 공유 파일을 건드리지 않고 개인 플랜 폴더를 숨겨 줍니다. 오너십은 CODEOWNERS가 맡습니다: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23.

라이프사이클은 ADR처럼

Michael Nygard의 2011년 글이 템플릿입니다. 결정은 "may be 'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement"이고, "If a decision is reversed, we will keep the old one around, but mark it as superseded"입니다 s9. Thoughtworks는 스펙 사용을 spec-first(작업 하나를 위해 한 번 작성), spec-anchored(기능이 발전하도록 유지), spec-as-source(스펙만 편집)로 나누고, 필자는 "I'd rather review code than all these markdown files"라고 덧붙입니다 s10. Superpowers는 spec-first 파일을 쓰고 영원히 보관합니다. 기본값이 drift입니다.

Drift와 gate

arXiv 논문은 문제를 이렇게 부릅니다: "silent spec-code drift -- code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair". 그리고 "a drift gate that makes spec-code divergence a blocking merge condition"을 제안합니다 s11. Spec Kit의 가이드도 경고합니다: "Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7. TrueFoundry는 거버넌스 논거를 직설적으로 말합니다: "forty-one specs and nine agent files aren't a tidiness problem", 그것들은 "forty-one unversioned behavior inputs and nine competing standing policies"이며, drift는 "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable". 같은 글은 스펙당 약 300줄, 상시 지시문 150에서 200개의 예산을 제안합니다 s13. 한 실무자는 수동 방식을 이렇게 설명합니다: "I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26.

비용

실험 결과 출처
현재 날짜를 보여주는 기능에 Spec Kit 적용 파일 8개, 텍스트 1,300줄 s14
OpenSpec 베이크오프, 같은 요구사항, 스펙 도구 대 순수 Claude Code OpenSpec이 빈틈 3개를 더 찾음. 코드 50% 증가, 순환 복잡도 50% 증가. 시간 2배, 비용 3배 s12
몇 달간 스펙 주도 개발을 한 팀 "two to three times as many tokens and take about twice as long". 코드가 나아졌다는 증거는 없음 s25

베이크오프는 실험 하나이고 작성자도 그렇게 밝히지만, 세 건 모두 방향은 같습니다. 그러니 아키텍처 경로에는 스펙을 쓰고, 한정된 경로는 한정된 채로 두고, 실무자들이 반복하는 두 줄을 따르세요: "don t spec too big / read the generated specs" s26.

월요일에 할 일

  • 스쿼드마다 docs/specs/<squad>/를 만들고, 폴더마다 해당 스쿼드의 리뷰어를 가리키는 CODEOWNERS 한 줄을 추가하세요.
  • 프로젝트 CLAUDE.md에 굵은 명령문 한 줄을 추가하세요: 플랜과 스펙은 docs/specs/<squad>/ 아래에 저장해야 하며 docs/superpowers/는 안 된다. 브레인스토밍을 한 번 돌리고 파일이 어디에 생겼는지 확인하세요.
  • 개인 플랜은 .git/info/exclude에 등록한 폴더로 옮기고, 개발자별 설정은 CLAUDE.local.md에 두되 이 파일도 ignore하세요.
  • 공유 스펙마다 헤더를 붙이세요: status(proposed, accepted, superseded), superseded-by, owner, paths, review-by.
  • drift gate를 작성하세요: status: accepted인 스펙마다 언급된 경로를 추출하고, 하나라도 없으면 풀 리퀘스트를 실패시킵니다. 셸이나 Python으로 약 15줄입니다.
  • 브랜치 규칙을 추가하세요: 풀 리퀘스트 없이는 어떤 스펙이나 플랜 커밋도 main에 들어가지 않습니다.
  • 저장소가 Sphinx 등으로 문서를 게시한다면 오늘 중으로 스펙 폴더를 exclude_patterns에 추가하세요.
  • 크기 예산을 정하세요: 스펙은 300줄 안팎으로 유지하고, 스쿼드 경계를 넘거나 다시 읽힐 작업에만 스펙을 씁니다.

더 읽어 보기

  • 헤더 체계를 고르기 전에 스펙 사용의 세 범주(spec-first, spec-anchored, spec-as-source)를 읽어 보세요. 라이프사이클은 spec-anchored 파일에만 의미가 있습니다 s10.
  • arXiv 논문은 경로 검사를 넘어 drift를 강제하는 전체 아키텍처까지 다룹니다. 15줄짜리 gate가 너무 거칠게 느껴질 때 유용합니다 s11.
  • Spec Kit 가이드는 세 가지 진화 흐름(Flow-Forward, Living Spec, Flow-Back)을 소개하며, 같은 커밋 규칙과 대응됩니다 s7.
  • 플레이북은 플랜과 diff의 동기화를 강제하는 훅을 제안합니다. 이에 대한 Reddit 스레드에는 43점과 현장 보고 댓글 27개가 있습니다 s5, s27.
  • 스펙 변경은 정책 변경이므로 실행 메타데이터와 함께 eval gate 뒤에 두어야 한다는 TrueFoundry의 주장은 CI 경로 검사 다음 단계입니다 s13.
  • 열려 있는 두 이슈, 1246(main 위의 플랜)과 939(무시되는 오버라이드)를 지켜보세요. 둘 중 하나가 닫히면 이 팩의 규칙 하나가 플러그인 기본값이 됩니다 s16, s18.
  • Marmelab의 전체 글은 1,300줄이 왜 생겼는지, Spec Kit이 어디서 효과가 있는지 설명합니다 s14.

출처

FAQ

첫날부터 다섯 가지 규칙이 전부 필요한가요?

아니요. CLAUDE.md 리디렉트와 Sphinx 제외는 10분이면 됩니다. 스펙이 처음 스쿼드를 넘나들 때 CODEOWNERS와 헤더를 추가하고, accepted 스펙이 한 스프린트 묵으면 drift gate를 추가하세요.

drift gate가 놓치는 것은 무엇인가요?

동작의 변경입니다. 언급된 경로가 아직 존재하는지만 확인하므로, 뒤집힌 조건은 통과합니다. 같은 커밋 규칙과 리뷰를 함께 쓰세요.

그냥 폴더를 gitignore하면 안 되나요?

나중에 스펙을 읽는 에이전트에게 그 파일이 필요하고, 중간 산출물까지 버전 관리되어야 감사 추적이 성립하기 때문입니다. okama 팀도 gitignore를 시도했다가, 커밋하고 빌드에서만 제외하는 방식으로 되돌렸습니다.