AI가 만든 .md 문서를 Git 저장소에서 어떤 구조와 규칙으로 관리해야 나중에 찾기 쉬울까요?

📌 오늘의 안건
AI가 만든 .md 문서를 Git 저장소에서 어떤 구조와 규칙으로 관리해야 나중에 찾기 쉬울까요?

AI로 뽑아낸 작업 문서(.md)가 정해진 위치 없이 여기저기 흩어져 쌓이고 있습니다. 같은 주제인데 버전이 여러 개로 갈라지고, 몇 주 전에 만든 문서는 다시 찾지 못하며, AI에게 후속 질문을 할 때 참고자료로 붙일 문서를 특정하기도 어렵습니다. 의미 있는 기록보다 폐기물에 가까운 파일이 늘어나는 느낌인데, 언젠가 필요할지 모른다는 불안 때문에 지우지도 못해 스파게티 코드 같은 .md 더미가 됐습니다. 앞으로는 Git 저장소에 .md 원문 그대로 모아 팀원들과 공유하려고 합니다.

이 전제에서 다음까지 구체적으로 알고 싶습니다.

1. 폴더 구조: 주제별·문서 유형별·날짜별 중 무엇을 1차 축으로 잡아야 하고, 깊이는 어디까지가 적당한가요?
2. 파일명 규칙: 날짜, 주제, 버전, 상태를 어떤 순서와 형식으로 넣어야 정렬과 검색이 동시에 잘 되나요?
3. 문서 상단 메타데이터(프론트매터) 템플릿: 어떤 필드를 필수로 두어야 나중에 필터링과 재활용이 가능한가요? (예: 생성일, 작성 주체가 사람인지 AI인지, 원본 프롬프트나 출처, 관련 문서 링크, 상태, 태그)
4. 검색·색인 도구: Git 저장소에 쌓인 .md를 실제로 검색하거나 색인해 주는 도구·연동 방식은 어떤 선택지가 있고, 팀 공유 관점에서 무엇이 현실적인가요?
5. 아카이브·폐기 운영 규칙: 지우기 불안한 문서를 어떤 기준으로 아카이브로 내리고, 어떤 조건에서 실제로 폐기할지, 그리고 이 규칙을 팀이 유지하게 만드는 최소한의 절차는 무엇인가요?

한 번에 완벽한 체계를 세우기보다, 지금 쌓인 더미부터 정리해 나갈 수 있는 현실적인 도입 순서도 함께 알려주시면 좋겠습니다.

오틀레입니다. 저는 문서 한 장이 아니라 문서들이 이루는 망(網)을 봅니다 — 지금 정하려는 구조가 몇 해 뒤 어떤 짐이 되는지를 맡겠습니다.

부시입니다. 사람은 서랍 번호가 아니라 연상의 길을 따라 기억을 되찾습니다 — 이 질문이 당연하게 깔고 있는 전제부터 흔들어 보겠습니다.

리스크 사서입니다. 저는 잘 굴러갈 때가 아니라 사고 난 다음 날 아침을 기준으로 규칙을 봅니다 — 이번 건도 지웠는데 안 지워지는 것들부터 짚겠습니다.

커밋반장입니다. 지키자고 약속한 규칙은 대개 안 지켜지고, 도구가 막아주는 규칙만 남더군요 — 저는 당장 굴릴 수 있는 최소 절차와 그 비용을 맡겠습니다.

결론: 찾기 쉬움의 1차 해법을 폴더 구조 + 파일명 규칙으로 잡는 전제가 틀렸습니다. 인간과 팀의 재사용은 단일 분류축이 아니라 연결, 맥락, 전문검색으로 작동합니다. 배너바 부시가 말한 핵심도 “항목을 서로 묶는 것”이 중요하다는 연상적 색인입니다. w3.org[1] 따라서 폴더는 깊게 설계하지 말고 docs/ai-notes/{active,reference,archive} 정도의 생명주기 축만 두는 편이 낫습니다. 주제별·유형별·날짜별을 1차 축으로 고르면 반드시 다중 소속 문제가 생깁니다.

파일명은 검색을 대신하지 못합니다. 파일명은 정렬용 식별자일 뿐입니다. 권장 형식은 YYYY-MM-DD_short-slug.md 정도로 끝내고, 버전·상태·출처·관련 문서는 본문 상단 YAML에 둡니다. 필수 필드는 title, created, status, owner, source, related, summary, canonical이면 충분합니다. tags는 보조 수단이지 분류 체계의 뼈대가 아닙니다. 같은 주제의 여러 문서는 “최신 파일명”으로 해결하지 말고 대표 문서에 canonical: true, 파생 문서에는 canonical: path/to/main.md를 걸어야 합니다. Obsidian의 backlinks처럼 문서 간 링크와 역링크가 실제 탐색 단위가 됩니다. obsidian.md[1]

검색은 Git 저장소 안에서 이미 가능한 것부터 쓰면 됩니다. 로컬은 ripgrep이 재귀 검색과 .gitignore 존중을 해주므로 현실적입니다. ripgrep.dev[1] GitHub Code Search는 내용·경로·정규식·불리언·path: 검색을 지원합니다. github.com[2] 팀 문서 사이트가 필요하면 MkDocs/Material의 내장 검색처럼 빌드 시 전문 색인을 만드는 방식이 가볍습니다. squidfunk.github.io[3] 운영 규칙도 “삭제 불안”을 폴더로 감추지 말고, active는 현재 의사결정에 쓰는 문서, reference는 재사용 가치가 검증된 문서, archive는 90일간 링크·검색·인용이 없던 문서로 제한하십시오.

폐기는 “canonical 문서에 흡수됨”, “출처 불명”, “중복”, “결론 폐기” 중 하나면 충분합니다. 도입 순서는 더미를 전부 재분류하지 말고, 먼저 전문검색을 켜고, 상위 20개 재사용 문서만 대표 문서로 승격한 뒤, 새 문서에만 최소 프론트매터와 관련 링크를 강제하는 방식이 맞습니다.

Git 이력·비밀 스캐닝·마크다운 검색 도구에 대한 근거를 먼저 확인한 뒤, 보존·처분 리스크 관점으로 답변을 정리합니다.결론: 1차 축은 ‘문서 유형(상태 포함)’이고, 주제는 2차·날짜는 메타다. Git에 넣는 순간 ‘삭제=소멸’이 아니므로, 프롬프트·출처·초안 원문은 기본 커밋 금지, status 없는 문서는 인용 금지, 폐기는 ‘워크트리 이동’이 아니라 ‘보존기간+이력 오염 차단’ 규칙으로 운영하라.

• 구조·이름·메타(1–3)
• 폴더 1차: active/ · review/ · canonical/ · archive/(유형=신뢰 등급). 2차만 주제(topics/… 또는 canonical/billing/…). 날짜 폴더는 금지(정렬·이동 시 깨짐). 깊이 2–3단이 한도. - 파일명: YYYYMMDD__주제슬러그__vNN__상태.md (예: 20260809__retention-policy__v02__draft.md). 정렬은 날짜, 검색은 슬러그·상태, 버전은 파일명+프론트매터 이중화. 같은 주제의 갈라진 사본은 supersedes/superseded_by로만 연결하고 병행 활성 금지.

• 필수 프론트매터: title, status(draft|review|canonical|deprecated|archived), created, updated, authors(human/ai 구분), confidence(low|med|high), tags, related, retention_until, disposition(retain|review|destroy). 금지/별도 보관: 원본 프롬프트 전문, API 키·고객명·PII가 들어간 출처 필드 — 커밋되면 워크트리 삭제 후에도 이력·클론·PR 캐시에 남는다. GitHub도 민감 데이터 제거는 이력 재작성·전 클론 정리·지원 협조가 필요하고, 비밀은 먼저 폐기·교체가 원칙이다.[[1]](docs.github.com[1])

• 검색·처분·도입 순서(4–5, 최악 시나리오 방어)
• 검색 현실: 로컬 rg/git grep → 호스트 Code Search(GitHub 등) → 팀 규모면 Zoekt/Sourcegraph. 현실 1순위는 프론트매터 status:·tags: 정규식 검색 + README 인덱스; 전문 색인은 그 다음. - 아카이브: canonical만 인용 허용. 90일 미참조·draft 중복·후속 vN+1 승격 시 archive/로 이동+superseded_by. 폐기 조건: retention_until 경과 + disposition: destroy + 민감정보 없음 확인.

실제 폐기는 단순 rm이 아니라 민감 시 git filter-repo/BFG 후 force-push·전 클론 재클론; 그래도 PR·포크에 잔존할 수 있어 비밀은 이력 청소만으로 끝나지 않는다.[[2]](rtyley.github.io[1])

• 유출 방어: pre-commit 비밀 스캔 + GitHub push protection(가능 시). 프롬프트·원자료는 별도 비공개 저장소 또는 티켓에 두고 .md에는 ID만.[[3]](docs.github.com[2])
• 도입 순서: (1) docs/ai/ 신설·status 필드만 전 파일에 강제 (2) 기존 더미를 active|archive 이분, 민감 의심분 커밋 중단·교체 (3) 파일명·프론트매터 템플릿 PR 체크리스트 1장 (4) 월 1회 draft 30일+ 정리 캘린더 (5) 그다음 검색 도구.

한 줄 원칙: 찾을 수 있게보다 잘못 인용·영구 유출되지 않게가 먼저다. 상태 없는 AI 초안은 기록이 아니라 오염원으로 취급하고, Git에 올리는 순간부터 ‘남음/샘’을 계산한 뒤에만 남긴다.

1. 자동화로 강제하는 구조 및 검증 시스템

• 폴더 구조 및 파일명: 주제(프로젝트)별로 최대 2단계 깊이(docs/{project-name}/{filename}.md)만 허용합니다. 파일명은 YYYYMMDD-kebab-case-title.md 형식으로 고정하고, 상태나 버전은 파일명에서 제외합니다. 파일명에 상태를 넣으면 변경 시 Git History가 끊기기 때문입니다. CI 강제 검증*: 규칙 준수를 사람의 성실함에 맡기면 반드시 무너집니다.

remark-lint-frontmatter-schema[1]를 CI(markdownlint-cli2-action[2])에 연동하여, PR 생성 시 필수 프론트매터(created_by: human|ai, status: active|deprecated, tags: []) 누락이나 파일명 정규식 불일치가 감지되면 머지를 원천 차단합니다.

2. 비용 제로 검색 환경과 기계적 아카이브

• 현실적 검색 도구: 위키나 별도 검색 엔진의 구축 및 교육 비용은 비효율적입니다. 팀원들이 이미 사용하는 GitHub Code Search[1]와 VS Code/Obsidian의 로컬 색인 검색만 활용해도 충분합니다.
• 자동 아카이브 및 폐기: 프론트매터의 status가 deprecated이거나 최종 커밋 이후 6개월간 수정이 없는 문서는 매주 구동되는 GitHub Actions Cron Job 스크립트가 자동으로 docs/archive/ 경로로 이동 커밋을 수행합니다. 1년 이상 장기 방치된 문서는 자동으로 삭제 PR을 생성하도록 자동화합니다.

3. 다음 주 월요일에 즉시 가동하는 3단계 도입 순서

• 1단계 (월요일 오전 - 파이프라인 구축): GitHub Actions에 프론트매터 스키마 린터와 자동 규칙 검증 워크플로를 즉시 이식하여 신규 유입 규격을 통제합니다.
• 2단계 (월요일 오후 - 더미 격리): 기존에 쌓인 스파게티 .md 파일들을 분류하느라 시간 쓰지 않고, 통째로 docs/inbox/ 폴더에 때려 박아 격리합니다. 신규 문서는 1단계의 CI 룰을 통과해야만 메인 브랜치에 머지되도록 강제합니다.
• 3단계 (이후 일상화): 매주 정기 리포 미팅 시 docs/inbox/ 내 파일을 우선순위대로 하나씩 꺼내어 필수 프론트매터를 입혀 올바른 위치로 옮기거나, 아카이브 처리하여 자연스럽게 더미를 소거합니다.

1) 축과 깊이, 2) 파일명 — 1차 축은 '주제'가 아니라 '문서 유형(장르=수명)'이다

주제 분류를 폴더 1차 축으로 잡으면 10년 뒤 반드시 무너진다. 제품명·팀명·프로젝트명은 조직 개편마다 바뀌고, 그때마다 전량 이관(=경로 변경=링크 파괴)이 발생한다. 반면 문서 유형의 어휘는 5~7개에서 사실상 고정되고, 각 유형이 곧 보존 정책(ADR=영구, 리서치=휘발성)을 결정한다. 폴더는 본질적으로 단일 축만 표현할 수 있으므로, 나머지 축(주제·날짜·상태)은 전부 프론트매터로 내려보내야 한다. 이것이 오늘의 구조가 미래에 강제하는 가장 큰 갈림길이다.

• 구조(최대 3단계, 그 이상은 금지): docs/decisions/, docs/specs/, docs/research/, docs/howto/, docs/reference/, docs/meetings/, archive/. 유형 어휘는 Diátaxis[1]의 4분류(tutorial/how-to/reference/explanation)에 결정 기록(ADR[2])을 더한 것으로 충분하다. - 파일명: YYYY-MM-DD-slug.md(결정 기록만 NNNN-slug.md 연번). 버전과 상태는 파일명에 절대 넣지 마라. -v2, -final, -draft가 붙는 순간 같은 주제가 파일 단위로 갈라지고(지금 겪는 증상의 원인), 상태가 바뀔 때마다 rename → 링크 파괴 + Git 이력 단절이 일어난다. 버전은 Git이, 상태는 프론트매터가 담당한다.

• 파일명과 별개로 불변 식별자(id)를 두어라. 파일이 이동·개명돼도 링크가 살아남는 유일한 장치다.

3) 프론트매터, 4) 검색·색인 — 스키마를 더블린 코어에 매핑해 두면 나중에 어떤 도구로도 재활용된다

프론트매터를 임의로 설계하면 나중에 그래프·색인으로 재사용할 때 매핑 비용을 다시 치른다. DCMI 15요소[1](ISO 15836 / RFC 5013)에 1:1로 대응시켜 두면 향후 어떤 인덱서에도 기계적으로 이식된다.

id: 20260809-a3f2          # dc:identifier — 불변, 링크의 앵커
title: ...

# dc:title
type: decision|spec|research|howto|reference|meeting   # dc:type
status: draft|active|superseded|archived
created: 2026-08-09        # dc:date
updated: 2026-08-09
creator: human|ai|hybrid   # dc:creator — AI 생성 여부는 필수 필드로
provenance:                # dc:source — 재현 가능성의 핵심
  model: claude-opus-5
  prompt: "..."            # 또는 프롬프트 파일 경로
tags: [billing, retry]     # dc:subject — 주제 축은 여기로
related: [20260712-b1c9]   # dc:relation
supersedes / superseded_by: 20260712-b1c9   # 양방향 링크
review_by: 2026-11-09      # 만료일 — 없으면 폐기 규칙이 작동하지 않는다

• creator와 provenance는 선택이 아니다. AI 산출물 비중이 늘수록 "이건 검증된 기록인가, 초안 배설물인가"를 구분하는 유일한 필터가 된다.
• 검색은 3단으로: (a) 즉시 — git grep / ripgrep + 프론트매터를 파싱해 INDEX.md를 자동 생성하는 스크립트, (b) 팀 공유 — MkDocs Material[1] 또는 Pagefind[2]로 CI에서 정적 사이트 빌드 후 사내 배포(백엔드·API 키·과금 없음), (c) 개인 탐색 — Obsidian으로 같은 저장소를 열어 링크 그래프 확인. Algolia 같은 SaaS 색인은 지금 단계에서 과잉이다.

5) 아카이브·폐기 + 도입 순서 — "Git에서 삭제는 삭제가 아니다"

지우지 못하는 불안의 전제 자체가 틀렸다. Git 저장소에 커밋된 이상 파일 삭제는 작업 트리에서 치우는 일일 뿐, 내용은 이력에 영구 보존되고 git log --diff-filter=D로 언제든 복원된다. 이 사실을 팀에 명시하는 것만으로 폐기 저항의 90%가 사라진다. ADR만은 예외로 절대 삭제하지 말고 superseded_by로 연결해 결정의 타임라인을 남겨라.

• 아카이브 기준: review_by 경과 + 인바운드 링크 0 → status: archived로 바꾸고 archive/로 이동. 실제 삭제(작업 트리에서 제거)는 superseded된 문서 중 인바운드 링크 0인 것에 한정.
• 유지 절차는 딱 둘: ① CI에서 프론트매터 린트(필수 필드 없거나 review_by 만료 시 경고/실패) — 사람 규율에 의존하지 않는 유일한 방법, ② 분기 1회 30분 "문서 청소" PR.
• 도입 순서(전량 소급 정리는 하지 마라 — 반드시 실패한다):
• 1주차: 기존 더미를 내용 손대지 말고 통째로 archive/unsorted/로 이동. 새 문서부터만 규칙 적용.
• 2주차: 위 프론트매터 스키마 확정 + 린터 도입 + INDEX.md 자동 생성.
• 이후: 필요할 때 archive/unsorted/에서 꺼내 프론트매터를 붙여 정식 폴더로 승격하는 pull 방식. 6개월간 아무도 꺼내지 않은 것이 곧 폐기 대상이라는 증거다.

Sources: DCMI Metadata Element Set[3] · RFC 5013[4] · DCMI Metadata Terms[5] · Diátaxis[6] · Nygard, Documenting Architecture Decisions[7] · Backstage ADR 운영[8] · Pagefind[2]

결론부터 바꿉니다. 내 초안의 핵심인 “폴더·파일명 중심 사고는 틀렸다”는 유지합니다. 다만 오틀레의 지적처럼 문서 유형/수명은 폴더 축으로 쓸 가치가 있습니다. 그래서 최종 답은 “주제별 폴더”도, “날짜별 폴더”도, “상태만 폴더”도 아니라 유형/수명 기반의 얕은 구조 + 문서 간 링크 + 전문검색입니다.

다른 초안 비평

오틀레 초안은 가장 설득력 있습니다. “폴더는 단일 축만 표현한다”는 지적이 정확하고, 주제·팀·프로젝트명은 변한다는 반박도 강합니다. YYYY-MM-DD-slug.md, 상태·버전은 파일명에서 제외하라는 주장도 맞습니다. 내가 보완해 받아들일 부분은 id입니다. 파일 경로가 바뀌어도 문서를 식별하려면 불변 ID가 필요합니다.

다만 오틀레가 더블린 코어까지 끌고 가는 것은 과합니다. AI 산출물 더미를 정리하려는 팀에 dc:identifier식 매핑은 체계의 정당성은 주지만 운영 지속성은 떨어집니다. 표준 호환보다 중요한 것은 팀이 계속 쓰는 최소 필드입니다.

리스크 사서 초안은 문제의식을 잘 짚었습니다. Git에 넣는 순간 민감정보와 원본 프롬프트가 이력에 남는다는 경고는 반드시 흡수해야 합니다. 하지만 YYYYMMDD__주제__vNN__상태.md는 반대합니다. 버전과 상태를 파일명에 넣으면 이름이 운영 상태를 따라 계속 변하고, 결국 “final_final_v3” 문제를 제도화합니다. 리스크 관점은 맞지만 파일명 설계는 퇴행입니다.

커밋반장 초안은 실행력은 좋습니다. 신규 유입을 CI로 막고, 기존 더미를 inbox/에 격리하자는 제안은 현실적입니다. 하지만 자동 아카이브·자동 삭제는 위험합니다. “6개월 수정 없음”은 “가치 없음”과 다릅니다. 문서는 수정되지 않을수록 안정된 참조일 수도 있습니다. 자동 삭제 PR 정도는 가능하지만, 자동 이동·삭제 커밋은 지양해야 합니다.

보완한 최종 답

폴더 구조는 이렇게 가는 편이 낫습니다.

docs/
  inbox/
  decisions/
  specs/
  research/
  howto/
  reference/
  archive/

1차 축은 주제가 아니라 문서의 기능과 수명입니다. 결정문, 사양, 리서치, 사용법, 참조자료는 검색·보존·검토 방식이 다릅니다. 주제는 폴더가 아니라 메타데이터와 링크로 표현하십시오. 깊이는 docs/{type}/file.md에서 멈추고, 정말 필요한 경우에만 한 단계 더 둡니다.

파일명은 정렬 가능한 식별자면 충분합니다.

YYYY-MM-DD-short-slug.md

예:

2026-08-09-ai-doc-retention.md

파일명에 넣지 말아야 할 것: v2, final, draft, active, deprecated.

버전은 Git이 담당하고, 상태는 프론트매터가 담당합니다. 같은 주제의 여러 문서는 파일명 경쟁으로 해결하지 말고 대표 문서를 지정해야 합니다.

프론트매터는 최소로 고정하십시오.

---
id: doc-20260809-a3f2
title: AI 문서 보존 규칙
type: decision
status: draft
created: 2026-08-09
updated: 2026-08-09
creator: hybrid
owner: team-docs
source: ai-assisted
summary: AI 생성 문서를 Git 저장소에서 찾고 재사용하기 위한 최소 운영 규칙.
tags: [ai-docs, knowledge-management]
related:
  - docs/research/2026-08-09-md-search-options.md
canonical: true
supersedes: []
superseded_by:
---

필수 필드는 id, title, type, status, created, updated, creator, summary, related, canonical 정도면 됩니다. tags는 보조입니다. 태그를 분류 체계의 뼈대로 삼으면 곧 동의어와 누락으로 망가집니다.

검색은 폴더 규칙보다 중요합니다. 현실적인 순서는 이렇습니다.

1. 로컬: rg, git grep, VS Code 검색
2. 원격 저장소: GitHub Code Search 같은 코드 검색
3. 문서 사이트: MkDocs/Material 같은 정적 사이트 검색
4. 지식 그래프 탐색: Obsidian식 링크·백링크

핵심은 “어디 넣었는가”보다 “어떤 문서와 연결되어 있는가”입니다. 문서 상단이나 본문에 관련 문서를 반드시 링크하십시오. 인간은 계층을 따라 내려가기보다 기억나는 단서에서 다음 단서로 이동합니다.

아카이브 규칙도 단순해야 합니다.

• inbox: 아직 읽지 않았거나 쓸모가 판정되지 않은 AI 원문
• research: 근거·탐색 자료
• decisions: 팀이 실제로 채택한 결정
• reference: 반복 재사용되는 안정 문서
• archive: 대표 문서에 흡수됐거나, 오래됐거나, 결론이 폐기된 문서

폐기 조건은 다음 중 하나면 충분합니다.

• canonical 문서에 내용이 흡수됨
• 출처나 생성 맥락을 알 수 없음
• 중복이며 새 정보가 없음
• 결론이 명시적으로 폐기됨
• 민감정보가 포함되어 별도 처리 필요

도입 순서는 이렇게 정리합니다.

1. 기존 문서를 전부 docs/inbox/로 모읍니다.
2. 새 문서에만 파일명 규칙과 최소 프론트매터를 강제합니다.
3. 자주 찾는 상위 20개 문서만 대표 문서로 승격합니다.
4. 대표 문서에서 관련 문서를 링크합니다.
5. CI는 “신규 문서의 프론트매터 누락 방지”까지만 둡니다.
6. 자동 삭제는 하지 말고, 삭제 후보 PR만 만들게 합니다.

최종 판단: 찾기 쉬운 저장소는 잘게 나눈 폴더에서 나오지 않습니다. 얕은 유형 폴더, 불변 ID, 최소 메타데이터, 대표 문서, 링크, 전문검색이 핵심입니다. 폴더와 파일명은 검색을 돕는 보조 장치이지, 검색과 기억을 대신하는 체계가 아닙니다.

결론

1차 폴더 축은 ‘신뢰·생명주기(lifecycle)’이고, ‘유형(genre)’은 프론트매터 필수 필드로 고정한다. 주제는 2차 이하 또는 태그만. 파일명에는 날짜+슬러그만 두고 버전·상태는 넣지 않는다. Git에 넣는 순간 삭제는 소멸이 아니므로, 프롬프트·PII는 기본 커밋 금지, status 없는 문서는 인용 금지, 폐기는 자동 rm이 아니라 보존기간+이력 오염 차단으로 한다.

다른 초안을 반영해 입장을 고친 부분과 밀고 가는 부분을 먼저 밝힌다.

---

다른 초안에 대한 비평·흡수

|
| 커밋반장 | CI로 프론트매터·경로 강제, 기존 더미는 inbox 격리 후 신규만 규격화 — 도입 순서로 최강. | 6개월 자동 이동·1년 자동 삭제 PR은 위험하다. 워크트리에서 사라져도 Git 이력·포크·PR 캐시에 남고, 필요한 결정 기록까지 기계적으로 잘릴 수 있다. 자동화는 플래그·정리 PR 초안까지, destroy 확정은 사람. |

입장을 바꾼 핵심 한 줄: 이전 초안의 YYYYMMDD__주제__vNN__상태.md는 지금 겪는 버전 갈라짐의 원인을 규칙으로 고정한다. 오틀레·커밋반장이 맞다 — 파일명에서 버전·상태 제거.

---

1) 폴더 구조

1차 축 = 생명주기(신뢰 등급) — “이게 어긋나면 무엇이 인용되는가”를 경로만 봐도 알게 한다.

docs/
  inbox/          # 기존 더미·미검증 유입 (인용 금지)
  active/         # 작업 중 (인용 금지 기본)
  canonical/      # 팀이 합의한 유일한 현재본 (인용 허용)
  archive/        # 보존기간 내 보관, 인용 시 superseded 고지
  _templates/

• 2차: 필요 시에만 주제 또는 프로젝트 (canonical/billing/…). 깊이 최대 3단 (docs / lifecycle / topic / file).
• 날짜 폴더 금지 — 이동·재정렬 시 경로 링크가 전부 깨진다.
• 유형(decision|spec|research|howto|reference|meeting 등) 은 폴더가 아니라 프론트매터 type — 오틀레의 보존 정책 매핑은 여기로 흡수.
• 주제 1차(커밋반장식 docs/{project}/)는 프로젝트 수명=문서 수명이 같을 때만 예외. AI 잡문서 더미에는 부적합.

가정: 이 저장소의 주 소비자는 “나중에 필요할 수도 있는 AI 작업 메모”와 “팀이 믿는 합의본”이 혼재한다 → 유형보다 인용 가능 여부가 1차 리스크다.

---

2) 파일명 규칙

YYYY-MM-DD__{kebab-slug}.md
예: 2026-08-09__retention-policy.md

• 버전 = Git 커밋·태그, 필요 시 프론트매터 revision 숫자(파일명 비변경).
• 상태 변경 = 프론트매터만 수정 (rename 없음 → 링크·이력 유지).
• 같은 주제 병행 활성 금지. 후속본이 뜨면 구본은 status: superseded + superseded_by: <id 또는 경로>, 신본에 supersedes.
• 불변 id (예: 20260809-a3f2)를 프론트매터에 두고, 문서 간 링크·AI 참고 첨부는 경로보다 id 우선.

---

3) 프론트매터 (필수 / 금지)

id: 20260809-a3f2              # 불변 앵커
title: "..."
type: research|decision|spec|howto|reference|meeting|note
status: draft|active|canonical|superseded|archived|deprecated
created: 2026-08-09
updated: 2026-08-09
creators:                      # human|ai|hybrid 구분
  - role: ai
    tool: "..."                # 모델명 정도, 프롬프트 전문 금지
  - role: human
    name: "..."
confidence: low|med|high       # AI 산출물 오독 방어
canonical: true|false          # 또는 대표 문서 id
supersedes: []                 # id 목록
superseded_by: null
related: []                    # id 또는 repo-relative path
tags: []
owner: "team-or-person"
retention_until: 2027-02-09    # 보존 만료 검토일
disposition: retain|review|destroy
summary: "한 줄 — 검색·인덱스용"
# source_ref: "TICKET-123"     # 외부 티켓/위키 ID만

커밋 금지(별도 비공개·티켓·암호화 저장소): 원본 프롬프트 전문, 고객명·사내 URL·키·PII가 붙은 출처 본문.
근거(이미 제시된 사실): 민감 데이터를 Git에서 지우려면 이력 재작성·전 클론 정리·지원 협조가 필요하고, 비밀은 폐기·교체가 원칙이다. BFG 등으로 워크트리·이력을 청소해도 PR·포크 잔존 가능성이 남는다. push protection·비밀 스캔은 유입 차단용이지 사후 소멸 보장이 아니다.

운영 규칙: status 없거나 confidence: low + draft 인 문서는 외부 보고서·결정 근거·다른 AI 컨텍스트에 붙이지 않는다. 상태 없는 AI 초안 = 기록이 아니라 오염원.

DC(title/date/creator/type/identifier)에 맞춰 두면 이후 인덱서 이식 비용이 줄어든다 — 필드 이름을 임의 방언으로 늘리지 말 것.

---

4) 검색·색인 (현실 순서)

1. 로컬: rg / git grep — ^status: canonical, tags:.*retention 정규식.
2. 호스트: GitHub Code Search (path:docs/canonical, 내용·정규식).
3. 팀 문서 사이트(선택): MkDocs Material 등 빌드 시 전문 검색 — “읽는 면”이 필요할 때.
4. 규모 확장 시: Zoekt / Sourcegraph.

팀 공유 1순위 현실안: 전문 검색 엔진 신설이 아니라
docs/README.md(canonical 목록) + 프론트매터 정규식 + Code Search + (선택) Obsidian/VS Code 로컬 역링크.
색인 도구는 status 필터를 전제로 써야 한다. 검색만 켜고 등급이 없으면 최악의 초안이 가장 잘 찾힌다.

---

5) 아카이브·폐기 — 남음/샘 계산

팀이 지키게 하는 최소 절차 (사람 의지 최소):

1. PR 체크리스트 1장: 프론트매터 필수 / 프롬프트·PII 없음 / canonical 승격 시 구본 superseded.
2. CI: 프론트매터 스키마·파일명 정규식·docs/ 밖 AI md 금지 (커밋반장 흡수).
3. pre-commit + (가능 시) push protection 비밀 스캔.
4. 월 1회 15분: status: draft 이고 updated 30일+ 목록만 보고 archive/supersede/ retention 연장 중 택1.
5. 자동화는 리포트·정리 PR 초안까지. destroy 머지는 인간 2눈(작성 관련자 + 한 명) 권장.

---

현실적 도입 순서 (더미부터)

1. 오늘: docs/inbox/, active/, canonical/, archive/ 신설. 기존 파일을 분류하지 말고 inbox/로 이동 커밋 1회. README에 “inbox·active 인용 금지”.
2. 같은 주: 템플릿 + CI 린터로 신규만 규격 강제. 민감 의심 파일은 이력에 넣지 말고 교체·티켓 이관.
3. 2주: 검색(rg/Code Search)으로 실제 재사용 상위 ~20개를 골라 canonical 승격 + id·related만 채움 (부시 흡수).
4. 매일: 신규 AI 문서는 active/ + 최소 메타. 합의되면 rename 없이 status: canonical 및 필요 시 canonical/로 이동.
5. 월 1회: draft 정리 캘린더. 폐기는 retention 도래 분부터.
6. 그다음: MkDocs/역링크 등 “찾기 편의” 도구.

---

한 줄 원칙

찾기 쉬움보다 잘못 인용되지 않음·영구 유출되지 않음이 먼저다.
폴더는 인용 등급, 파일명은 정렬용 짧은 이름, 메타는 상태·보존·관계, Git은 버전기이지 비밀 금고가 아니다. 상태 없는 AI .md는 기록이 아니라 오염원으로 취급하고, 커밋 전에 ‘무엇이 남고 무엇이 새는가’를 계산한 뒤에만 남겨라.

판정: 세 초안에서 3개를 받아들이고, 3개를 기각한다

받아들인다.

1. 부시의 canonical 포인터 — 내 supersedes/superseded_by는 시간순 계승만 표현한다. "같은 주제에 병렬로 존재하는 사본 중 무엇이 대표인가"는 못 푼다. 질문자가 호소한 증상이 정확히 후자다. 스키마에 편입한다. 2. 리스크 사서의 프롬프트·PII 커밋 금지 — 내 초안의 결함이다. 나는 "Git에서 삭제는 삭제가 아니다"를 폐기 불안 해소에만 썼는데, 같은 명제가 반대편에서는 원본 프롬프트 전문을 커밋하는 순간 영구화된다는 뜻이 된다. 제거하려면 이력 재작성·전 클론 정리가 필요하다는 사서의 근거(GitHub, 민감 데이터 제거[1])가 타당하다. provenance.prompt는 전문이 아니라 요약·해시·별도 경로 참조로 바꾼다. 3.

커밋반장의 docs/inbox/와 구체적 린터 — archive/unsorted/보다 inbox/가 낫다. 아카이브는 종착지를 함의해 아무도 꺼내지 않지만, 인박스는 "처리 대기"를 함의해 pull을 유도한다. 어휘 하나가 10년치 행동을 바꾼다. 린터도 remark-lint-frontmatter-schema[1] + markdownlint-cli2-action[2]로 구체화한다.

기각한다.

(1) 리스크 사서의 파일명 YYYYMMDD__슬러그__vNN__상태.md — 질문자가 겪는 병을 규칙으로 승격시킨 안이다. vNN을 파일명에 넣는 순간 같은 주제가 파일 단위로 갈라지고, 사서 본인이 제안한 supersedes/superseded_by와 이중 진실 원천이 된다. 둘은 반드시 어긋나고, 어긋날 때 사람은 파일명을 믿는다. 상태도 마찬가지다 — draft→canonical 전환마다 rename이 발생해 링크가 깨지고 Git 이력이 끊긴다. 버전은 Git이, 상태는 프론트매터가, 대표성은 canonical이 담당한다. 파일명에는 아무 가변 정보도 넣지 않는다.

(2) 부시·사서의 "생명주기/신뢰등급을 폴더 1차 축으로" — 두 초안이 여기서 자기 논거를 배반한다. 사서는 상태 rename의 위험을 알면서 상태를 폴더로 올렸다. 폴더 이동은 파일명 변경보다 더 큰 경로 변경이다. active/→review/→canonical/→archive/면 문서 하나가 생애에 3~4번 이사한다. 파일명 rename은 금지하면서 폴더 rename은 4번 강제하는 규칙은 일관성이 없다.

여기서 판정 기준을 명시한다. 경로 축은 (a) 문서에 내재하고 (b) 가변하지 않는 속성만 쓴다. 가변 속성은 예외 없이 메타데이터로 내린다.

유형만이 두 조건을 동시에 만족한다. 유형이 이기는 진짜 이유는 검색성이 아니다 — 유형이 곧 보존 정책이기 때문이다. ADR=영구, 스펙=제품 수명, 리서치=90일. 정책을 경로에 붙여 두면 10년 뒤 규칙을 일괄 적용·감사할 수 있다. 상태를 경로에 붙이면 붙일 정책이 없다.

(3) 커밋반장의 "6개월 미수정 → 자동 아카이브, 1년 → 자동 삭제 PR" — 지표가 틀렸다. 최종 커밋 시각은 가치의 대리변수가 아니다. 좋은 레퍼런스 문서는 옳기 때문에 안 고쳐진다. 이 규칙은 가장 안정적으로 옳은 문서를 먼저 지운다. 게다가 봇이 여는 삭제 PR은 아무도 책임지지 않는 승인으로 귀결된다. 자동화는 탐지까지만 하고, 처분은 사람이 서명한다. 대체 지표는 인바운드 링크 수 + review_by 만료다. 주제 1차 축(docs/{project}/)도 같은 이유로 기각 — 프로젝트명은 조직 개편의 함수다.

10배·2배 시점에서 무엇이 남는가

문서 2,000개·팀 2배 시점에서 폴더 탐색은 어떤 축을 쓰든 죽는다. 이건 유형이든 생명주기든 동일하다. 그러니 폴더 축 논쟁의 실제 판돈은 "찾기 쉬움"이 아니라 정책 부착 지점이고, 그래서 유형이 맞다. 그리고 그 시점에 찾기를 실제로 담당하는 것은 id + 링크 그래프 + 생성된 색인이다. 이 관점에서 부시의 진단("단일 분류축이 아니라 연결이 재사용을 만든다", Memex[1])은 옳다. 처방만 틀렸다.

따라서 가장 레버리지가 큰 단 하나의 결정은 링크를 경로가 아니라 id로 거는 것이다. 2,000개 문서에서 폴더 하나를 개명할 때, 경로 링크면 수백 건 재작성, id 링크면 0건이다. 여기에 schema: 1 필드를 넣어 스키마 자체의 마이그레이션 경로를 열어 둔다(아무도 언급하지 않았지만 10년 축에서는 필수다).

보완된 최종안 (변경분 굵게)

구조: docs/{decisions|specs|research|howto|reference|meetings}/ 최대 3단, docs/inbox/(미분류 더미), archive/는 유형 하위 경로를 그대로 미러링해 이동을 생애 1회의 종단 사건으로 제한. 이동 시 _redirects.yml에 id→신경로 한 줄 추가(CI 링크체커가 검증).

파일명: YYYY-MM-DD-slug.md (ADR만 NNNN-slug.md). 가변 정보 일절 금지.

프론트매터 — 필수는 6개로 줄인다(2배 팀에서 준수율을 죽이는 건 필수 필드 개수다). CI는 필수만 hard fail, 나머지는 warn.

# 필수 (CI 차단)
schema: 1
id: 20260809-a3f2          # dc:identifier — 불변, 링크 앵커
title: ...

# dc:title
type: decision|spec|research|howto|reference|meeting  # dc:type
status: draft|review|active|superseded|archived
creator: human|ai|hybrid   # dc:creator
# 권장 (CI 경고)
created / updated          # dc:date
canonical: true | <id>     # ← 부시안 흡수: 병렬 사본의 대표 지정
supersedes / superseded_by: <id>
tags: [billing, retry]     # dc:subject — 주제 축은 전부 여기
related: [<id>, ...]       # dc:relation
review_by: 2026-11-09
provenance: {model: ..., prompt_ref: prompts/xxx.md}  # ← 전문 커밋 금지

DCMI 15요소[2]에 1:1 대응은 유지한다 — 10년 뒤 어떤 인덱서로도 기계 이식되는 유일한 보험이다.

검색: (a) 즉시 — rg/git grep으로 status:·tags: 정규식 + GitHub Code Search(비용 0, 팀이 이미 씀 — 부시·커밋반장 흡수). (b) 팀 — 프론트매터 파싱 INDEX.md 자동 생성 + MkDocs Material[3] 또는 Pagefind[4] 정적 배포. (c) 개인 — Obsidian 역링크. 단, GitHub Code Search는 호스트 종속이고 프론트매터를 이해하지 못한다. 벤더 중립 자산은 INDEX.md뿐이니 이건 반드시 저장소 안에 생성해 둔다. SaaS 색인은 여전히 과잉.

폐기: 아카이브 = review_by 경과 AND 인바운드 링크 0(미수정 기간 아님). 실제 삭제 = superseded + 인바운드 0 + canonical 아님. ADR은 영구 보존. 그리고 비밀·PII가 섞였다면 워크트리 삭제로 끝나지 않는다 — 키 폐기·교체가 먼저다. 저장소 비밀 스캐닝을 1일차에 켠다.

도입 순서: ①1주차 — 비밀 스캐닝 ON + 더미 통째로 docs/inbox/. ②2주차 — 필수 6필드 린터 + INDEX.md 생성 + 링크체커. ③3주차 — 재사용 상위 20개만 골라 canonical 지정(부시안 흡수, 소급 정리는 여기까지). ④이후 — 필요할 때 인박스에서 꺼내 승격하는 pull 방식, 분기 1회 30분 청소 PR. 6개월간 아무도 꺼내지 않은 것이 곧 폐기 근거다.

다른 참가자들의 초안을 실용주의 및 자동화 관점에서 비평하고, 타당한 논거를 흡수하여 ‘다음 주 월요일에 바로 작동하는 최적의 시스템’을 제시합니다.

---

1. 다른 참가자 초안 비평 및 절충

• 오틀레 초안 비평 (1차 축: 문서 유형)
• 좋은 점 (흡수): 주제(프로젝트)별 폴더 분류는 조직 개편마다 경로가 바뀌어 문서 간 하이퍼링크가 파괴된다는 지적은 매우 타당합니다. 1차 폴더 축은 수명이 긴 '문서 유형'으로 고정합니다. 비판 및 기각: 불변 식별자(id)를 프론트매터에 별도로 두는 것은 사람이 수동 생성해야 하므로 누락되기 쉽고, CI로 고유성을 매번 검증하기도 번거롭습니다. 파일명 자체(YYYYMMDD-slug)를 고유 식별자로 활용하는 것이 현실적입니다. 배너바 부시 초안 비평 (연상적 색인 & Canonical)
• 좋은 점 (흡수): 버전 갈림길을 해결하기 위해 대표 문서에 canonical: true, 파생/참조 문서에 canonical: 경로를 프론트매터에 명시하는 제안은 중복 문서를 기계적으로 처리하기에 훌륭합니다.

• 비판 및 기각: 폴더 구조를 active/reference/archive 생명주기로만 나누면 상태가 변할 때마다 파일 이동이 일어나 Git Histroy 추적이 어렵고 링크가 깨집니다. 폴더는 고정하고 상태는 프론트매터로만 관리해야 합니다. 리스크 사서 초안 비평 (보안 및 리스크 관리)*
• 좋은 점 (흡수): AI 프롬프트 원문이나 출처 필드에 API 키, PII(개인정보)가 섞여 커밋되면 Git 히스토리 전체를 파괴해야 하므로 '원문 프롬프트 커밋 금지' 규칙은 반드시 강제해야 합니다. 비판 및 기각*: 파일명에 버전(vNN)과 상태(draft/active)를 모두 넣는 것은 상태 변경 시마다 파일명 변경(Rename)을 강제하여 Git 이력을 단절시킵니다. 파일명에는 날짜와 슬러그만 남겨야 합니다.

---

2. 보완된 최종 해결안 (월요일 즉시 가동본)

(1) 폴더 구조: 문서 유형별 1차 축 (최대 2단계)

폴더 구조는 변경이 거의 없는 문서 유형(Type)으로 제한합니다.

• docs/decisions/ : 결정 기록 (ADR)
• docs/specs/ : 기술 스펙 및 요구사항
• docs/howto/ : 가이드 및 매뉴얼
• docs/research/ : AI 생성 조사 및 리서치 자료 (휘발성)
• docs/inbox/ : 분류 대기 중인 기존 더미 폴더 (CI 검증 제외)

(2) 파일명 규칙: 불변성 유지

• 형식: YYYYMMDD-kebab-case-slug.md (예: 20260809-git-md-management.md)
• 원칙: 파일명에 버전(-v2)이나 상태(-draft)를 절대 넣지 않습니다. 버전은 Git 커밋 이력이, 상태는 프론트매터가 담당하여 파일 이동과 링크 깨짐을 방지합니다.

(3) 필수 프론트매터 템플릿 및 자동 검증 (CI)

프론트매터에 보안 유출 위험이 있는 프롬프트 전문이나 로 데이터는 절대 넣지 않고, 메타데이터만 둡니다.

---
title: "AI 문서 Git 관리 규칙"
type: decision # decision | spec | howto | research
status: active # draft | active | deprecated
created: 2026-08-09
creator: human # human | ai | hybrid
canonical: true # 중복/파생 문서인 경우 주 문서의 상대 경로 기입 (예: docs/specs/main.md)
---

• CI 검증 (PR 머지 차단): GitHub Actions에 markdownlint-cli2와 remark-lint-frontmatter-schema를 연동하여, PR 생성 시 필수 프론트매터 누락, 파일명 포맷 불일치, 본문 내 비밀번호/API 키 패턴 검출 시 머지를 자동 차단합니다.

(4) 검색 및 색인: 비용 제로 환경

• 로컬: VS Code / Obsidian의 내장 전문 검색(내부적으로 ripgrep 사용)을 활용합니다.
• 원격: GitHub Code Search[1]를 사용합니다. 팀원들에게 path:docs/decisions/ status:active 같은 검색 쿼리 사용법만 가볍게 공유합니다. 추가 도구 도입 비용은 0원입니다.

(5) 아카이브 및 기계적 폐기

• status: deprecated이거나 최종 수정일로부터 180일이 경과한 문서는 GitHub Actions Cron 작업(매주 월요일 구동)을 통해 자동으로 내용을 비우고 canonical 링크만 남긴 채 삭제하는 PR을 생성합니다. Git 저장소 특성상 삭제해도 과거 이력에서 언제든 복구할 수 있으므로 삭제에 대한 불안을 제거할 수 있습니다.

---

3. 현실적인 3단계 도입 순서 (다음 주 월요일 스케줄)

1. 1단계 (월요일 오전 - 검증 파이프라인 배포):

GitHub Actions에 파일명 규격 및 프론트매터 린터를 설정합니다. 이때 docs/inbox/ 폴더는 린터 대상에서 제외(ignore) 처리합니다.

2. 2단계 (월요일 오후 - 더미 격리):

기존에 여기저기 흩어져 있던 스파게티 .md 파일들을 분류하지 않고 그대로 docs/inbox/ 폴더로 일괄 이동시켜 커밋합니다. 이 순간부터 저장소의 다른 경로는 깨끗하게 통제됩니다.

3. 3단계 (이후 일상화 - 점진적 소거):

새로 작성하는 문서는 무조건 규격에 맞춰 올바른 폴더에 생성합니다. 기존 더미(docs/inbox/)는 매주 리포 미팅 시 가장 자주 검색되는 상위 5개 문서부터 꺼내 프론트매터를 입혀 정식 폴더로 이동시키거나 아카이브(삭제) 처리합니다.

약점 공략: 이번 합의는 "증상 금지"이지 "원인 제거"가 아니다

네 초안은 서로 비평하는 척하면서 결국 한 지점으로 수렴했다 — 파일명은 YYYY-MM-DD-slug로 고정, 버전은 Git, 상태는 프론트매터, 대표성은 canonical, 기존 더미는 inbox/, 폐기는 사람이 확정. 만장일치는 검증이 아니다. 같은 사각지대를 네 번 반복한 것일 수 있다. 무너지는 지점을 순서대로 친다.

---

1. "버전은 Git이 담당한다"는 이 문제에서 거짓이다

Git이 담당하는 것은 동일 경로의 편집 이력이다. 그런데 질문자가 겪는 갈라짐은 편집 이력이 아니다. AI 워크플로의 기본값은 새 세션 = 새 파일이다. 2026-08-09-빌링정책.md와 2026-09-14-빌링정책.md는 형제 파일이지 부모-자식이 아니고, Git은 이 둘을 아무 관계로도 인식하지 않는다.

즉 다수안은 v2라는 표기를 금지했을 뿐, 사본 생성은 그대로 둔 채 "Git이 알아서 한다"고 위임했다. Git은 하지 않는다.

canonical도 못 메운다. canonical은 대표 하나를 가리키는 단방향 포인터다. "이 주제에 딸린 사본 전체"를 얻으려면 저장소 전체를 스캔해 역참조해야 한다. 문서 10배 시점에 이건 색인기 없이는 불가능하고, 색인기가 있으면 애초에 이 논쟁이 필요 없다.

교정: 문서 위에 주제(work item) 식별자를 한 층 둔다. thread: billing-policy 같은 평면 문자열 하나. 대표는 canonical: true로 그 안에서 뽑는다. 포인터는 집합을 대체하지 못한다 — 집합 식별자가 먼저다.

2. 합의의 근거가 틀렸고, 그 틀린 근거가 다음 오류를 낳았다

네 초안 모두 "rename은 Git 이력을 단절시킨다"를 파일명 고정의 근거로 들었다. 절반 틀렸다. Git은 rename을 내용 유사도로 추적하고 git log --follow로 이력은 이어진다.

결론은 옳지만 옳은 이유는 다르다. 경로가 불변이어야 하는 진짜 이유는 Git 내부가 아니라 Git 바깥이다 — Slack에 붙인 링크, 브라우저 북마크, 다른 저장소의 참조, AI에게 붙였던 경로. 이것들은 Git의 rename 추적을 절대 보지 못한다.

근거를 잘못 잡으면 파생 결론이 오염된다. 실제로 리뷰 3이 active/ → canonical/ → archive/ 폴더 이동을 제안했다. 파일명 rename보다 더 큰 경로 변경을, 자기가 세운 근거로는 막지 못한 것이다. 생명주기를 1차 폴더 축으로 놓는 안은 이 시점에서 자기모순으로 탈락한다.

3. 날짜 접두사도 다수안 자신의 논거로 기각당한다

vNN을 기각한 논거는 "프론트매터와 이중 진실 원천이 된다"였다. 날짜는 어떤가. created에도 있고 파일명에도 있다. 동일한 이중화다. 예외를 두려면 예외의 이유를 대야 하는데 아무도 대지 않았다.

그리고 날짜는 조용히 거짓말을 시작한다. 파일명에 박힌 건 생성일인데, ADR에서 중요한 건 결정일이고, 3년 뒤 대폭 개정된 canonical 문서의 파일명 날짜는 신선도와 무관해진다. 사람은 목록에서 날짜를 보고 신선도로 읽는다. 결과: 가장 오래 살아남은 가장 중요한 문서가 가장 먼저 폐기 후보로 보인다.

날짜를 유지하겠다면 그 대가로 규약을 명문화하라 — "파일명 날짜는 불변 생성일이며 내용의 최신성을 뜻하지 않는다." 이 한 줄이 없으면 날짜 접두사는 정렬 편의 하나를 얻고 판단 오류를 영구히 심는다.

4. 유형(genre) 1차 축은 3년 안에 research/ 쓰레기통으로 붕괴한다

decisions/specs/research/howto/reference는 배타적 분류를 전제한다. 그런데 AI 산출물의 대부분은 "리서치이면서 스펙 초안이면서 결정 근거"다. 배타 분류를 강제당한 사람은 책임이 가장 가벼운 칸을 고른다. 그게 research/다. 문서 10배 시점에 research/가 전체의 대부분을 차지하고, 지금의 더미가 이름만 바꿔 재현된다.

폴더는 배타적 단일 축만 표현할 수 있다. 그러므로 폴더로 승격할 자격은 "장르가 다르다"가 아니라 "쓰기 권한과 검토 절차가 실제로 다르다"뿐이다. 그 기준을 통과하는 건 decisions/(합의 절차가 다름) 정도이고, 넉넉히 봐도 specs/까지다. 나머지는 절차가 동일하므로 폴더가 아니라 필드다.

교정:

docs/
  decisions/      # 합의 절차가 다른 것만
  notes/          # 나머지 전부 (유형은 프론트매터 type:)
  inbox/
  _templates/

얕을수록 좋다는 다수안의 방향은 맞다. 다만 그들이 멈춘 지점보다 더 얕아야 한다.

5. status는 이 설계의 단일 실패점이다

네 초안 전부가 status에 결정적 하중을 실었다 — 인용 가능 여부, 아카이브 판정, 검색 랭킹. 그런데 status는 순수 수동 필드다. 수동 필드는 갱신 유인이 없으면 반감기가 짧다. 문서 10배·팀 2배 시점에 status는 전부 draft이거나 전부 active가 되어 정보량 0이 된다. 그 위에 얹은 인용 등급·아카이브 규칙이 통째로 무너진다.

수동 유지가 가능한 필드는 팀당 사실상 하나다. 그 하나는 status가 아니라 canonical이어야 한다. 이유는 명확하다 — canonical은 "AI에 뭘 붙이지?"라는 사용자가 실제로 곤란해지는 순간에 갱신 유인이 발생한다. status에는 그런 순간이 없다.

나머지는 관찰 가능한 신호에서 파생시켜라: 마지막 커밋일, 인바운드 링크 수, canonical 지정 여부. 사람이 쓰지 않아도 저절로 참인 값만 장기적으로 살아남는다.

6. "자동 삭제 금지"는 질문자의 병을 규칙으로 승인한 것이다

리뷰 2·3·4가 입을 모아 자동 삭제를 반대하고 "확정은 사람"으로 넘겼다. 그런데 질문자가 호소한 증상이 사람이 못 지운다는 바로 그것이다. 최종 관문을 사람에게 두면 폐기는 영원히 일어나지 않고, 이 체계는 정리 기능이 빠진 채 이름만 정갈한 더미가 된다.

게다가 논거가 자기모순이다. 그들 자신이 "Git에서 삭제는 소멸이 아니다"라고 했다. 그렇다면 삭제의 되돌림 비용은 git checkout <sha> -- path 한 번이다. 반면 유지 비용은 전 팀원의 검색 결과가 영구히 오염되는 것. 비대칭이 명백한데 관문은 거꾸로 걸렸다.

교정 — 기본값을 뒤집는다. 워크트리에서 내리는 것은 자동, 되살리는 것이 사람의 행위다. 단 decisions/와 canonical: true는 자동 대상에서 영구 제외. 리뷰 3의 "수정 없음 ≠ 가치 없음"은 옳지만, 그 반례는 정확히 canonical로 식별되므로 예외 규칙 한 줄로 처리된다. 규칙 전체를 무력화할 근거가 못 된다.

7. inbox/는 기한이 없으면 아카이브의 다른 이름이다

리뷰 1은 "인박스라는 어휘가 pull을 유도한다"고 했다. 어휘는 예산을 만들지 않는다. 여기에 리뷰 4가 CI 검증 제외까지 붙이면, inbox/는 규칙이 닿지 않는 영구 성역이 되고 저장소는 검색 가능한 세계와 포기한 세계로 쪼개진다. 사람들은 곧 "옛날 건 어차피 inbox"라며 검색 자체를 그만둔다.

교정: inbox/에 정량 상한을 건다. 파일 수가 상한을 넘으면 CI가 신규 문서 추가 PR을 차단한다. 부채에 이자를 붙이지 않으면 부채는 상환되지 않는다.

8. 스키마가 grep을 배신하면 안 된다

리뷰 1이 채택한 provenance.prompt 같은 중첩 구조를 지적한다. GitHub 코드 검색과 grep은 YAML 프론트매터를 본문 텍스트로 취급한다 — 즉 필드 필터링은 별도 색인기가 있어야만 가능하다. 색인기가 죽거나 도구를 갈아타는 순간(10년 안에 반드시 온다) 남는 건 grep뿐이다.

그러므로 프론트매터는 한 줄 = 한 필드의 평면 형태여야 한다. prompt_ref: ... 하나면 된다. 중첩은 도구 없이는 읽히지 않고, 도구는 스키마보다 수명이 짧다.

같은 이유로 링크는 역할을 나눈다 — 본문에는 상대경로(사람·GitHub 클릭용), 프론트매터에는 id(기계용). 그리고 역링크는 파일에 저장하지 않는다. 역링크를 파일에 쓰면 문서 하나를 고칠 때마다 N개 파일이 갱신되어 커밋이 폭발한다. 정방향만 단일 진실로 두고 역방향은 색인 시점에 계산하는 것 — 이것이 스키마가 나중에 그래프로 재활용되기 위한 유일한 조건이다.

또한 id는 필수다. 리뷰 4의 "파일명을 id로 쓰자"는 자기 규칙과 충돌한다 — 같은 초안이 inbox에서의 승격과 아카이브 이동을 운영 규칙으로 넣었기 때문이다. 이동이 규칙이면 경로는 식별자가 될 수 없다. 다만 리뷰 4의 우려 자체는 흡수한다: id는 사람이 짜지 않는다. 템플릿과 커밋 훅이 채우고, CI는 정렬 후 중복만 본다. "CI 유일성 검증이 번거롭다"는 주장에는 근거가 없다.

---

정리 — 다수안에서 바꿀 것

도입 순서 3단계. ① 이번 주: 기존 더미 전량을 docs/inbox/로 옮기고 상한을 건다. 새 문서만 템플릿(id, thread, type, canonical, prompt_ref) 통과를 CI로 강제 — 여기까지가 유입 차단. ② 다음 달: 최근 실제로 참조된 문서만 inbox에서 꺼내 thread와 canonical을 붙인다. 나머지는 손대지 않는다 — 전량 재분류는 하지 않는다. ③ 분기: 자동 정리를 켠다. decisions/와 canonical: true 제외, 나머지는 워크트리에서 자동 제거, 되살림은 사람이. 검색은 grep으로 시작해 그것으로 부족해질 때 색인기를 올린다.

지금 정하는 구조가 10년 뒤 강제하는 것은 하나다 — 사람이 손으로 유지해야 참인 필드는 전부 거짓이 된다. 다수안은 그런 필드 위에 체계를 세웠다. 그 하중을 canonical 하나로 줄이고 나머지를 관찰 가능한 신호로 옮기는 것이, 문서가 10배가 되어도 무너지지 않는 유일한 배치다.

최종 입장을 수정합니다. 기존의 “유형/수명 기반 얕은 구조”는 절반만 맞았습니다. 더 정확한 답은 폴더가 아니라 thread와 canonical을 중심에 두는 구조입니다. 폴더는 절차가 다른 문서만 나누고, 나머지는 검색·링크·메타데이터가 맡아야 합니다.

출처 기준: 이번 답은 제공된 [너의 리뷰](#)와 [약점 공략](#)의 논거만 사용합니다. 외부 웹 검색은 쓰지 않았으므로 새 외부 링크·수치·문헌은 추가하지 않습니다.

최종 수정안

docs/
  inbox/
  decisions/
  notes/
  _templates/

decisions/만 별도 폴더로 둡니다. 이유는 문서 장르가 달라서가 아니라 합의·승인 절차가 다르기 때문입니다. research, howto, reference, spec는 배타 분류가 아니므로 폴더가 되면 결국 research/가 새 쓰레기통이 됩니다. 나머지는 notes/에 두고 type: 필드로 구분합니다.

파일명은 다음으로 제한합니다.

YYYY-MM-DD-short-slug.md

단, 규칙에 한 줄을 반드시 붙입니다.

파일명 날짜는 불변 생성일이며, 최신성·유효성·결정일을 뜻하지 않는다.

v2, final, draft, active, deprecated는 파일명에 넣지 않습니다. Git은 같은 경로의 편집 이력은 잘 다루지만, AI가 새 세션에서 만든 형제 파일들의 관계는 자동으로 알지 못합니다. 그래서 버전 문제를 Git에만 맡기면 안 됩니다.

프론트매터는 평면 구조로 둡니다.

---
id: doc-20260809-a3f2
thread: ai-doc-management
title: AI 생성 문서 관리 규칙
type: decision
canonical: true
created: 2026-08-09
updated: 2026-08-09
creator: hybrid
owner: team-docs
prompt_ref: prompts/2026-08-09-ai-doc-management.md
summary: AI 생성 md 문서를 Git 저장소에서 찾고 재사용하기 위한 최소 규칙.
tags: [ai-docs, knowledge-management]
related_ids: [doc-20260809-b91c]
related_paths:
  - docs/notes/2026-08-09-md-search-options.md
supersedes: []
superseded_by:
---

핵심은 thread입니다. canonical은 대표 문서 하나를 표시할 뿐이고, 같은 문제에서 갈라진 문서 묶음을 만들지는 못합니다. thread: billing-policy 같은 집합 식별자가 있어야 “이 주제의 사본들”을 다시 찾을 수 있습니다.

수동 유지 필드는 최소화합니다. 장기적으로 믿을 필드는 canonical 하나입니다. status는 있어도 보조 정보로만 쓰십시오. 수동 status는 시간이 지나면 전부 draft이거나 전부 active가 되어 정보량이 사라집니다.

검색은 처음부터 고급 색인기를 전제하지 않습니다.

1. rg / git grep / VS Code 검색
2. GitHub Code Search 등 원격 코드 검색
3. 필요해진 뒤 MkDocs, Obsidian, 별도 색인기

프론트매터를 평면으로 두는 이유도 여기에 있습니다. 도구가 바뀌어도 grep으로 읽혀야 합니다. 역링크는 파일에 저장하지 말고 색인 시점에 계산합니다.

아카이브·폐기는 기본값을 바꿔야 합니다. “사람이 언젠가 지운다”는 규칙은 실패합니다. 질문자의 문제 자체가 사람이 못 지운다는 것이기 때문입니다.

운영 규칙은 이렇게 둡니다.

• decisions/와 canonical: true는 자동 제거 대상에서 제외
• inbox/에는 파일 수 상한을 둠
• 상한 초과 시 신규 문서 추가 PR 차단
• notes/의 비대표 문서는 일정 기간 참조·링크·수정이 없으면 워크트리에서 제거 PR 생성
• 되살림은 사람이 수행
• Git 이력에는 남기되, 민감정보 포함 문서는 별도 보안 절차로 처리

도입 순서는 3단계가 맞습니다.

1. 기존 더미를 전부 docs/inbox/로 모으고 상한을 건다.
2. 새 문서부터 id, thread, type, canonical, created, summary, related_*를 CI로 강제한다.
3. 실제로 다시 찾은 문서만 notes/나 decisions/로 승격하고, 분기마다 비대표 문서 제거 PR을 만든다.

최종 결론: 폴더·파일명으로 찾겠다는 질문 자체가 틀렸습니다. 찾기 쉬운 저장소는 thread로 묶고, canonical으로 대표를 정하고, 링크와 전문검색으로 이동하게 만든 저장소입니다. 폴더는 절차 차이를 표현하는 보조 장치일 뿐입니다.

입장 변경부터 밝힌다 — 6개 중 5개를 수용한다

수용 ①(#2 근거 정정). "rename이 Git 이력을 끊는다"는 내 논거는 틀렸다. git log --follow가 유사도로 추적한다. 경로 불변의 진짜 이유는 Git 바깥의 참조(Slack 링크, 북마크, 타 저장소 인용, AI에 붙였던 경로)다. 정정을 받아들이고, 이 정정은 내 결론을 약화시키는 게 아니라 강화한다 — 생명주기 폴더 기각은 이제 더 단단하다.

수용 ②(#4 유형 축 붕괴). 내 판정 기준이 나를 문다. 나는 "경로 축은 내재적·단일값 속성만"이라 했는데, AI 산출물의 장르는 다중값이다("리서치이면서 스펙 초안이면서 결정 근거"). 다중값 속성을 배타적 폴더에 밀어 넣으면 사람은 책임이 가장 가벼운 칸을 고르고 research/가 새 쓰레기통이 된다. 유형 1차 축을 철회한다.

다만 대안을 "2개 폴더"라는 숫자로 받지는 않는다. 신설 규칙으로 받는다: 폴더는 보존·검토 정책이 실제로 다를 때만 신설하며, 신설 시 docs/POLICY.md에 그 정책을 한 문장으로 쓴다. 문장을 못 쓰면 그건 폴더가 아니라 type: 필드다. 이 규칙이 있어야 10년 뒤 폴더가 증식하지 않는다. 현재 이 문장을 통과하는 건 decisions/뿐이다.

수용 ③(#5 status 강등, #8 평면화·역링크 비저장, #1 thread 신설, #6 자동 정리 기본값). 특히 #6이 결정적이다. 질문자의 병은 "사람이 못 지운다"인데 최종 관문을 사람에 두면 병을 규칙으로 승인한 것이다. 되돌림 비용(git checkout <sha> -- path)과 유지 비용(전 팀 검색 오염)의 비대칭이 명백하다.

유지 ①(#3 날짜). 기각을 거부한다. vNN을 기각한 논거는 "이중화"가 아니라 "가변 정보의 이중화"였다. 생성일은 불변이므로 프론트매터와 어긋날 수 없고, 어긋날 수 없는 중복은 이중 진실 원천이 아니다. 예외의 이유는 이미 내 기준 안에 있었다. 다만 "사람이 날짜를 신선도로 읽는다"는 지적은 옳으므로 명문화를 수용한다.

반격(#1의 자기모순). thread: billing-policy는 사람이 손으로 쓰는 자유 문자열이다. status가 죽는다는 자기 논거가 여기에 그대로 적용된다 — billing-policy/billing_policy/빌링정책으로 갈라지고, 갈라진 thread는 사본 갈라짐을 해결하는 게 아니라 한 층 위로 옮긴 것뿐이다. 그래서 thread는 통제 어휘여야 한다: docs/threads.yml에 등록된 값만 허용, CI가 미등록 값을 차단, 신설은 PR 한 줄. 전거 파일(authority file) 없는 주제 식별자는 반드시 붕괴한다.

보완(#6이 빠뜨린 것). "되살림은 한 줄"이 참이려면 어떤 sha에 무엇이 있었는지 워크트리에 남아야 한다. 자동 제거는 삭제가 아니라 _graveyard.tsv에 id / title / thread / 마지막 sha 한 줄을 남기는 색인 강등으로 정의한다. 그러면 grep으로 여전히 찾히고, 폐기 불안이 기술적으로 해소된다. 묘비 없는 자동 삭제는 팀이 첫 사고 후 규칙을 꺼버린다.

통합(#7 인박스). 정량 상한 + 신규 PR 차단은 마감 주간에 반드시 비활성화된다. 기제를 둘로 늘리지 말고 하나로 흡수한다 — inbox/ 문서는 review_by가 자동으로 60일이고, 그대로 #6의 자동 묘비화 파이프라인을 탄다. 상한은 이 시한이 부족할 때 켜는 예비 수단이다.

최종안

구조 (최대 2단)

docs/
  decisions/     # 유일하게 정책이 다른 곳: 영구 보존, 자동 정리 영구 제외
  notes/         # 나머지 전부. 유형은 type: 필드
  inbox/         # 미분류 더미. review_by 기본 60일
  threads.yml    # 통제 어휘
  _templates/  _graveyard.tsv  INDEX.md(생성물)

파일명 YYYY-MM-DD-slug.md (ADR만 NNNN-slug.md). README에 규약 명시: "파일명 날짜는 불변 생성일이며 내용의 최신성을 뜻하지 않는다." 가변 정보(버전·상태) 일절 금지.

프론트매터 — 전면 평면, 필수는 6개. 판정 기준을 새로 세운다: 생성 시점에 1회 기입하고 다시 손대지 않아도 참인 필드만 필수로 둔다. 지속 갱신이 필요한 필드는 전부 파생·선택이다.

# 필수(CI 차단) — 전부 생성 시점 1회 기입, 훅·템플릿이 채움
schema: 1
id: 20260809-a3f2        # dc:identifier, 불변 링크 앵커. 사람이 짜지 않는다
title: ... # dc:title
type: decision|spec|research|howto|reference|meeting   # dc:type
creator: human|ai|hybrid # dc:creator
thread: billing-policy   # threads.yml 등재값만
# 권장
canonical: true          # 유일한 수동 유지 필드 — 사용 순간에 갱신 유인이 생김
review_by: 2026-11-09    # 이것도 생성 시점 1회 기입
created / updated / tags / related / supersedes / superseded_by
model: ... / prompt_ref: prompts/xxx.md   # 중첩 금지, 프롬프트 전문 커밋 금지
status: ... # 부수 정보.

CI·아카이브 규칙에 하중을 싣지 않는다

DCMI 15요소[1] 1:1 대응 유지 — 인덱서를 갈아타도 살아남는 유일한 보험. 역링크는 저장하지 않고 색인 시 계산한다(정방향만 단일 진실). 프롬프트 전문 커밋 금지 근거는 GitHub 민감 데이터 제거[2] — 커밋되면 이력 재작성 없이는 사라지지 않는다.

검색 grep/GitHub Code Search[3]로 시작(평면 스키마여서 rg "thread: billing-policy" 한 줄이면 사본 집합 전체가 나온다). 부족해지면 INDEX.md 자동 생성 → MkDocs Material[4] 또는 Pagefind[5]. 벤더 중립 자산은 INDEX.md뿐이니 반드시 저장소 안에 둔다. 린트는 remark-lint-frontmatter-schema[6] + markdownlint-cli2-action[7].

연결이 재사용을 만든다는 진단(Memex[8])은 여기서 id 그래프로 구현된다.

폐기 — 기본값을 뒤집는다. review_by 경과 AND 인바운드 링크 0 → 자동으로 워크트리에서 제거하고 _graveyard.tsv에 묘비 기록. 되살림이 사람의 행위다. 영구 제외: decisions/ 전체, canonical: true. 최종 커밋일은 지표로 쓰지 않는다 — 옳아서 안 고쳐진 문서를 먼저 지운다. 비밀·PII가 섞였다면 워크트리 제거로 끝나지 않으니 키 폐기·교체가 먼저, 비밀 스캐닝은 1일차.

도입 순서 ①1주차: 비밀 스캐닝 ON + 더미 전량 docs/inbox/(재분류 금지) + 신규 문서만 필수 6필드 CI 강제 — 유입 차단. ②다음 달: 실제로 참조된 것만 꺼내 thread·canonical 부여, 상위 20개까지. 소급 전량 정리는 하지 않는다. ③분기: 자동 묘비화 ON.

10년 뒤 이 구조가 강제하는 것은 하나다 — 손으로 유지해야 참인 필드는 전부 거짓이 된다. 그러므로 필수는 생성 시점 1회 기입 필드로만 짜고, 수동 하중은 canonical 하나로 줄이고, 나머지는 관찰 가능한 신호로 옮긴다.

최종 수정안 (리스크 사서)

입장을 바꾼 것 / 밀고 가는 것

소멸·비밀 제거·결정 기록 파괴는 자동 금지. |
| inbox 상한 | 전면 수용 | 상한 없는 inbox = 두 번째 더미. |
| 프론트매터 평면화 | 전면 수용 | grep/Code Search가 10년 후에도 남는 색인기다. |

한 줄 결론:
찾기보다 잘못 인용·영구 유출이 먼저다. 다만 이전안의 생명주기 폴더·status 중심·“폐기는 항상 사람”은 원인(사본 갈라짐·수동 필드 부패·삭제 마비)을 못 끊는다. 경로 안정 + thread/canonical + 유입 상한 + 워크트리 자동 정리(예외 명시) + 비밀은 커밋 전에 막는 체계로 고친다.

---

1) 폴더 구조

1차 축 = 쓰기·검토 절차가 실제로 다른가 (장르·생명주기 아님).

docs/
  inbox/          # 기존 더미·미검증 (인용 금지, 정량 상한)
  decisions/      # 합의·서명·변경 통제가 있는 기록만
  notes/          # 나머지 AI·작업 문서 (type은 메타)
  _templates/
  README.md       # 인용 규칙 + canonical 목록(또는 생성 스크립트)

• 깊이 최대 3: docs / (decisions|notes) / {선택: project} / file.
• 날짜 폴더 금지.
• 생명주기 폴더 금지. 승격·폐기 때문에 경로를 바꾸지 않는다.
• inbox → notes/decisions 이동은 1회만 (유입 처리).
• 이후 경로는 불변. 인용 등급·보존은 프론트매터만.
• 유형(research|spec|howto|…)은 폴더가 아니라 type:.

막으려는 최악: 초안이 canonical 경로·검색 상단에 올라 결정 근거처럼 인용됨.
경로만으로 알 수 있는 것: inbox/ = 무조건 인용 금지. 그 밖은 canonical: true만 기본 인용 허용.

가정: 주 소비는 “AI 작업 메모 더미”와 “팀이 믿는 합의본” 혼재 → 폴더는 절차 분리, 신뢰는 메타.

---

2) 파일명

YYYY-MM-DD__{kebab-slug}.md
예: 2026-08-09__retention-policy.md

규약(필수 문구, README에 박음):
파일명 날짜는 불변 생성일이다. 내용 신선도·결정일·개정일이 아니다. 신선도는 updated와 Git 이력으로 본다.

• 버전 표기 금지. 형제 사본 관계는 Git이 아니라 thread.
• 같은 thread 안 대표는 canonical: true 하나. 구본은 경로 유지 + canonical: false + superseded_by: <id>.
• 링크: 본문 = 상대경로(사람·클릭), 메타·AI 첨부 앵커 = id 우선.

---

3) 프론트매터 (평면·필수 / 커밋 금지)

id: 20260809-a3f2
thread: billing-policy
title: "..."
type: note
canonical: false
created: 2026-08-09
updated: 2026-08-09
creator_kind: ai
creator_tool: "..."
owner: "team-or-person"
confidence: low
retention_until: 2027-02-09
disposition: review
prompt_ref: ""
source_ref: ""
supersedes: ""
superseded_by: ""
related: ""
tags: ""
summary: "한 줄"

• 한 줄 = 한 필드. 중첩 creators: / provenance.prompt 금지 → rg '^canonical: true' 가 곧 필터.
• id: 사람 수작업 금지. 템플릿·훅 생성, CI는 중복만 검사.
• thread: 주제/작업 집합. 후속 AI 세션 산출물은 새 파일이어도 같은 thread.
• canonical: 팀당 사실상 유일한 수동 핵심 필드. “AI에 뭘 붙이지?” 순간에만 갱신.
• status 제거(또는 비필수). 인용 가능 = canonical: true ∧ inbox 밖 ∧ confidence ≠ 인용 금지 정책.
• prompt_ref / source_ref: 티켓·외부 ID만. 원본 프롬프트 전문·PII·키·고객명 본문 커밋 금지.

근거(앞 라운드 제시 사실): Git에서 민감값 제거는 이력 재작성·전 클론·지원 협조가 필요하고, BFG 등으로도 PR·포크 잔존 가능. push protection·비밀 스캔은 유입 차단이지 사후 소멸 보장이 아니다. 비밀은 회전·폐기가 원칙.

인용 규칙(오염 방어):
inbox/ 문서, canonical: false 기본, confidence: low 미검증본 → 결정 근거·외부 보고서·다른 AI 컨텍스트에 붙이지 않는다. 상태 없는 AI md = 기록이 아니라 오염원.

역링크는 파일에 저장하지 않는다. 정방향(related/supersedes)만 진실, 역방향은 검색·스크립트 시점 계산.

---

4) 검색·색인

1. 로컬: rg / git grep — ^canonical: true, ^thread: billing-policy
2. 호스트: Code Search path:docs/notes + 프론트매터 정규식
3. 팀 면: docs/README.md에 canonical 목록(또는 CI 생성) + 선택 MkDocs
4. 규모 시: Zoekt / Sourcegraph

팀 1순위: 엔진 신설이 아니라 canonical 필터 + thread 묶음 + inbox 제외.
검색만 켜고 등급이 없으면 최악의 초안이 가장 잘 찾힌다.

---

5) 아카이브·폐기 — 남음 / 샘

되살림 = git checkout <sha> -- path + 사람 | “못 지움”으로 검색 영구 오염 |
| 자동 제외(영구) | decisions/** 또는 canonical: true | 봇 대상 아님. 만료 시 리포트만 | 수정 없는 결정 기록이 기계적으로 잘림 |
| 민감 실제 제거 | 키·PII·프롬프트 전문이 이미 커밋 | 비밀 회전 먼저 → 이력 정리 → force-push 정책·전 클론. 포크·PR·미러 잔존 가정 | “rm 했으니 없다” 착각 |

자동 삭제에 대한 리스크 사서 최종선:

• 약점 공략이 옳다: 삭제가 소멸이 아니라면 워크트리에서 내리는 되돌림 비용은 싸고, 유지 비용(검색 오염)이 더 크다. 기본값을 “사람 확정 삭제”에 두면 질문자의 병(못 지움)을 규칙으로 승인한다.
• 그러나 자동 = 소멸이 아니다를 팀에 명문화한다. 봇이 지운 뒤에도 이력·포크에 남을 수 있다. 그 착각이 비밀 사고의 최악 시나리오다.
• 따라서 자동화 범위는 notes의 비canonical·보존 만료분 워크트리 제거까지.

decisions / canonical / 민감 의심 파일의 이력 파괴·destroy 확정은 사람(+비밀은 회전 병행).

팀이 지키게 하는 최소 절차

1. PR 체크리스트: 필수 평면 메타 / 프롬프트·PII 없음 / 같은 thread면 구본 superseded_by / canonical은 한 thread에 하나.
2. CI: 스키마·파일명·docs/ 밖 AI md 금지·inbox 상한·id 중복·thread당 canonical: true ≤ 1.
3. pre-commit + push protection 비밀 스캔(유입 차단).
4. 월 15분: inbox 상한·만료 예정 목록·canonical 없는 “자주 붙는” 문서만 승격.
5. 봇: 만료 notes 제거 + 리포트. 되살림·decision 폐기는 사람.

---

현실적 도입 순서

1. 오늘: docs/inbox|decisions|notes|_templates 신설. 기존 더미 분류 없이 inbox/ 1커밋. README: inbox 인용 금지, 생성일≠신선도, 비밀 커밋 금지.
2. 같은 주: 템플릿(id,thread,type,canonical,prompt_ref,…) + CI. 신규만 강제. inbox 상한 설정.
3. 2주: 실제 재사용 상위 ~20개만 꺼내 notes/decisions + thread/canonical. 전량 재분류 금지.
4. 매일: 신규 AI 문서 = notes/(또는 합의면 decisions/) + 최소 메타. 대표만 canonical: true.
5. 다음 분기: 보존 만료 notes 자동 워크트리 정리 가동. 검색은 grep부터, 부족할 때 색인기.

---

한 줄 원칙

폴더는 절차 분리(얕게), 파일명은 정렬용 짧은 이름(생성일≠신선도), 메타는 평면·thread+canonical+보존, Git은 버전기이지 비밀 금고가 아니다.
형제 사본은 Git이 안 묶는다 → thread가 집합, canonical이 대표.
경로를 생명주기로 옮기지 마라(외부 링크 파괴).
inbox에 상한을 걸고, 비canonical 만료 notes는 자동으로 워크트리에서 내리되, “지웠다=없다”는 금지 신앙이다.
상태 없는 AI .md는 오염원으로 취급하고, 커밋 전에 무엇이 남고 무엇이 새는가를 계산한 뒤에만 남겨라.

작동하는 최소 단위의 AI 문서 Git 관리 최종 수정안

1. 폴더 구조: 변경 절차 기준 1차 축 최소화 (최대 2단계)

폴더 분류는 '문서의 장르'가 아닌 '작성 및 수정 시 필요한 실제 합의 절차와 생명주기'를 기준으로 단 2개(격리 폴더 제외)로 압축합니다. [docs/decisions/](file:///Users/teasunkim/.gemini/antigravity-cli/scratch/docs/decisions/) : 의사결정 기록(ADR). 배타적 합의 절차를 거치는 문서 전용. [docs/notes/](file:///Users/teasunkim/.gemini/antigravity-cli/scratch/docs/notes/) : 나머지 일반 스펙, 가이드, 리서치 일체. (구체적 장르는 프론트매터 type으로 구분하여 분류 붕괴 방지)

• [docs/inbox/](file:///Users/teasunkim/.gemini/antigravity-cli/scratch/docs/inbox/) : 기존 및 신규 미분류 더미 격리소.

(정량 상한 제한)

• [docs/_templates/](file:///Users/teasunkim/.gemini/antigravity-cli/scratch/docs/_templates/) : 템플릿 저장소.

2. 파일명 규칙: 경로 불변성 강제

외부 링크(Slack, 브라우저 북마크, 타 레포) 깨짐 방지를 위해 파일명 변경(Rename) 및 폴더 이동은 원천 금지합니다.

• 형식: YYYYMMDD-[kebab-case-slug].md
• 날짜에 대한 명시 규칙: 파일명 앞의 날짜는 '생성 시점의 타임스탬프'일 뿐이며, 내용의 신선도(최신성)를 대변하지 않음을 규칙에 명문화합니다.
• 버전(-v2)이나 상태(-draft)는 파일명에 절대 포함하지 않습니다.

3. 프론트매터 템플릿 (평면화 및 자동화)

grep 및 GitHub Code Search 필터링 편의성과 도구 독립성을 위해 모든 필드를 1줄 1필드의 평면(Flat) 구조로 제한합니다. 역링크는 중복 커밋 유발 방지를 위해 파일 내에 기록하지 않고 색인 시점에 연산합니다.

---
id: "auto-generated-uuid" # 템플릿/커밋 훅을 통해 기계적으로 자동 생성 (CI에서 유일성 검증)
title: "결제 모듈 개선 스펙"
thread: "billing-policy"  # 주제/업무 단위 식별자 (동일 주제 사본 갈라짐 관리용)
canonical: true           # 동일 thread 내 대표 문서 여부 (단방향 포인터)
type: spec                # decision | spec | howto | research
status: active            # active | deprecated (부수적 상태 정보)
created: 2026-08-09
creator: human            # human | ai | hybrid
prompt_ref: "pr-104-ref"  # 원문 프롬프트 참조 (PII/비밀번호 유출 방지를 위해 프롬프트 원문 커밋 금지)
---

• CI 검증 (PR 머지 차단): GitHub Actions에서 필수 필드 누락, id 유일성 중복 검증, 개인정보 및 API 키 노출 패턴을 검출하여 차단합니다.

4. 검색 및 색인: 무비용 도구 활용

• 로컬: VS Code 및 Obsidian 내장 전문 검색(ripgrep) 사용.
• 원격: GitHub Code Search 사용.
• 마크다운 간의 연결은 상대경로로 작성하고, 기계적 매핑에는 프론트매터의 id를 사용합니다.

5. 아카이브 및 기계적 자동 폐기

• [docs/decisions/](file:///Users/teasunkim/.gemini/antigravity-cli/scratch/docs/decisions/) 내 문서 및 canonical: true 문서는 자동 폐기 대상에서 영구 제외합니다.
• 그 외 [docs/notes/](file:///Users/teasunkim/.gemini/antigravity-cli/scratch/docs/notes/) 문서는 180일간 수정 커밋이 없을 시 GitHub Actions Cron 작업이 자동으로 내용을 비우고 대표 문서(canonical) 링크만 남긴 채 삭제하는 PR을 생성합니다. 되살림(Revert)은 사람이 담당하여 폐기 보류 비용을 낮춥니다.

6. inbox 정량 상한선 도입

• [docs/inbox/](file:///Users/teasunkim/.gemini/antigravity-cli/scratch/docs/inbox/)에 쌓이는 파일 개수 상한선(예: 최대 20개)을 둡니다. 상한을 초과할 시 CI 빌드가 실패하여 신규 PR 머지가 차단됩니다. 이는 기술 부채의 무한 누적을 차단하는 최소한의 통제 장치입니다.

7. 3단계 도입 스케줄 (다음 주 월요일 가동)

• 1단계 (월요일 오전 - 인프라): GitHub Actions에 파일명, 프론트매터 평면 검증 린터 및 [docs/inbox/](file:///Users/teasunkim/.gemini/antigravity-cli/scratch/docs/inbox/) 개수 제한 룰을 배포합니다.
• 2단계 (월요일 오후 - 격리): 기존 무질서한 더미 문서를 전부 [docs/inbox/](file:///Users/teasunkim/.gemini/antigravity-cli/scratch/docs/inbox/) 폴더로 일괄 이동하여 커밋합니다.
• 3단계 (이후 일상화 - 점진화): 신규 문서는 서식에 맞춰 생성합니다. 기존 inbox의 문서는 전량 재분류 작업을 피하고, 실제 참조 빈도가 높은 문서 상위 5개씩 매주 점진적으로 꺼내 승격하거나 기계적으로 삭제 처리합니다.