From f767161c9e1e10cc063e3c4d40074d0e44eeb462 Mon Sep 17 00:00:00 2001 From: JeongUk Park Date: Sat, 25 Jul 2026 00:57:40 +0900 Subject: [PATCH 1/4] =?UTF-8?q?docs:=20=EC=A0=80=EC=9E=A5=EC=86=8C=20?= =?UTF-8?q?=EC=9C=84=EC=83=9D(repo=20hygiene)=20=EA=B7=9C=EC=95=BD=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/conventions/repo-hygiene.md | 21 +++++++++++++++++++++ policies/core.yaml | 6 ++++++ 2 files changed, 27 insertions(+) create mode 100644 docs/conventions/repo-hygiene.md diff --git a/docs/conventions/repo-hygiene.md b/docs/conventions/repo-hygiene.md new file mode 100644 index 0000000..57418b9 --- /dev/null +++ b/docs/conventions/repo-hygiene.md @@ -0,0 +1,21 @@ +# 저장소 위생 (repo hygiene) + +## Why + +이 조직의 제품 저장소는 대부분 OSS로 공개된다. 제품과 무관한 잡동사니가 섞이면 기여자가 무엇이 제품이고 무엇이 노이즈인지 구분하기 어려워지고, 공개 저장소의 신호 대 잡음비가 떨어진다. 저장소는 "이 제품을 이해하고 기여하는 데 필요한 것"만 담아야 한다. + +## 제품 저장소에 두지 않는 것 + +- **인프라·운영(ops) 전용 도구** — 거버넌스 점검 스크립트, 배포·레지스트리 조작 등 특정 인프라에만 쓰이는 것. 개인 dotfiles나 private 운영 저장소로 분리한다. +- **AI 에이전트의 세션별 작업 노트·휘발성 컨텍스트·내부 히스토리 덤프.** +- **특정 사용자 환경에만 유효한 로컬 설정.** + +## 제품 저장소에 두는 것 (위 금지에 해당하지 않음) + +- **CI 워크플로·린트·포맷 설정** 등 저장소가 실제로 쓰는 자동화. +- **`CLAUDE.md`·`AGENTS.md`** 등 에이전트 작업 지침. 단 내용은 손으로 유지하지 말고 rutter가 렌더한 것(`pilot apply`)을 우선한다. +- **설계 결정 근거(ADR)·아키텍처 문서.** 이건 잡음이 아니라 제품의 **왜(Why)** 다 — [문서 작성 규약](documentation.md)의 정신과 같다. "context·history를 넣지 마라"가 설계 이유까지 지우는 쪽으로 해석되면 안 된다. + +## 판단 기준 + +한 파일이 위생 대상인지 헷갈리면 이렇게 묻는다 — **"이 저장소를 처음 보는 기여자가 제품을 이해하거나 기여하는 데 이게 필요한가?"** 필요하면 남기고, 특정 운영자·AI 세션·인프라에만 쓸모 있으면 밖으로 뺀다. diff --git a/policies/core.yaml b/policies/core.yaml index 08c0642..0de791a 100644 --- a/policies/core.yaml +++ b/policies/core.yaml @@ -29,3 +29,9 @@ rules: category: documentation statement: "조직 구조가 바뀌면 docs/maps의 지도를 먼저 갱신한다." rationale: "낡은 지도는 좌초를 부른다 — 지도가 현행을 반영해야 나머지 문서와 자동화가 신뢰를 얻는다." + + - id: repo.hygiene + level: info + category: documentation + statement: "제품(대개 OSS) 저장소에는 제품 이해·기여에 필요한 것만 둔다 — 인프라·운영 도구나 AI 세션 잡음은 개인/private 저장소로 분리한다." + rationale: "공개 저장소의 신호 대 잡음비를 지킨다. 단 설계 근거(ADR·Why)는 잡음이 아니라 제품의 일부다 — 세션 노이즈와 설계 이유를 혼동하지 않는다." From 16db75126ca29376cb010bd496500cc4a0cdf899 Mon Sep 17 00:00:00 2001 From: JeongUk Park Date: Sat, 25 Jul 2026 01:04:45 +0900 Subject: [PATCH 2/4] =?UTF-8?q?docs:=20repo-hygiene=EC=9D=84=20doc=20?= =?UTF-8?q?=EC=A0=84=EC=9A=A9=EC=9C=BC=EB=A1=9C=20(PolicySet=20rule=20?= =?UTF-8?q?=EC=A0=9C=EA=B1=B0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/conventions/repo-hygiene.md | 2 ++ policies/core.yaml | 6 ------ 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/conventions/repo-hygiene.md b/docs/conventions/repo-hygiene.md index 57418b9..b93eb4a 100644 --- a/docs/conventions/repo-hygiene.md +++ b/docs/conventions/repo-hygiene.md @@ -1,5 +1,7 @@ # 저장소 위생 (repo hygiene) +> **적용 범위**: 이 규약은 **제품 저장소**(대개 OSS로 공개되는 것)를 위한 것이다. 도구를 호스팅하는 private 운영 저장소는 이 규약의 *대상*이 아니라 잡동사니를 옮겨 담는 *목적지*다 — 자기가 존재 이유인 도구를 비우라는 뜻이 아니다. 또한 이것은 사람·에이전트의 **판단형 가이드**이며 기계 검증(PolicySet check) 대상이 아니라 문서(convention)로 둔다. + ## Why 이 조직의 제품 저장소는 대부분 OSS로 공개된다. 제품과 무관한 잡동사니가 섞이면 기여자가 무엇이 제품이고 무엇이 노이즈인지 구분하기 어려워지고, 공개 저장소의 신호 대 잡음비가 떨어진다. 저장소는 "이 제품을 이해하고 기여하는 데 필요한 것"만 담아야 한다. diff --git a/policies/core.yaml b/policies/core.yaml index 0de791a..08c0642 100644 --- a/policies/core.yaml +++ b/policies/core.yaml @@ -29,9 +29,3 @@ rules: category: documentation statement: "조직 구조가 바뀌면 docs/maps의 지도를 먼저 갱신한다." rationale: "낡은 지도는 좌초를 부른다 — 지도가 현행을 반영해야 나머지 문서와 자동화가 신뢰를 얻는다." - - - id: repo.hygiene - level: info - category: documentation - statement: "제품(대개 OSS) 저장소에는 제품 이해·기여에 필요한 것만 둔다 — 인프라·운영 도구나 AI 세션 잡음은 개인/private 저장소로 분리한다." - rationale: "공개 저장소의 신호 대 잡음비를 지킨다. 단 설계 근거(ADR·Why)는 잡음이 아니라 제품의 일부다 — 세션 노이즈와 설계 이유를 혼동하지 않는다." From 5cd2f1b2b6e5bed2b9353dd90b01a4a68891a8f4 Mon Sep 17 00:00:00 2001 From: JeongUk Park Date: Sat, 25 Jul 2026 01:16:13 +0900 Subject: [PATCH 3/4] =?UTF-8?q?docs:=20repo-hygiene=EC=97=90=20=ED=95=AD?= =?UTF-8?q?=ED=95=B4=20=EC=BB=A8=EC=85=89=20=EB=B0=98=EC=98=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/conventions/repo-hygiene.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/conventions/repo-hygiene.md b/docs/conventions/repo-hygiene.md index b93eb4a..4f31df6 100644 --- a/docs/conventions/repo-hygiene.md +++ b/docs/conventions/repo-hygiene.md @@ -1,23 +1,23 @@ # 저장소 위생 (repo hygiene) -> **적용 범위**: 이 규약은 **제품 저장소**(대개 OSS로 공개되는 것)를 위한 것이다. 도구를 호스팅하는 private 운영 저장소는 이 규약의 *대상*이 아니라 잡동사니를 옮겨 담는 *목적지*다 — 자기가 존재 이유인 도구를 비우라는 뜻이 아니다. 또한 이것은 사람·에이전트의 **판단형 가이드**이며 기계 검증(PolicySet check) 대상이 아니라 문서(convention)로 둔다. +> **적용 범위**: 이 규약은 **제품 저장소**(대개 OSS로 공개되는 배)를 위한 것이다. 도구를 싣고 있는 private 운영 저장소는 이 규약의 *대상*이 아니라 잡짐을 옮겨 싣는 *부두 창고*다 — 자기가 실으라고 있는 화물을 버리라는 뜻이 아니다. 또한 이것은 사람·에이전트의 **판단형 항로 지침**이며, 기계 검증(PolicySet check)이 아니라 문서(convention)로 둔다. ## Why -이 조직의 제품 저장소는 대부분 OSS로 공개된다. 제품과 무관한 잡동사니가 섞이면 기여자가 무엇이 제품이고 무엇이 노이즈인지 구분하기 어려워지고, 공개 저장소의 신호 대 잡음비가 떨어진다. 저장소는 "이 제품을 이해하고 기여하는 데 필요한 것"만 담아야 한다. +배는 항해에 필요한 것만 싣는다. 갑판에 잡짐이 쌓이면 뒤따라 오르는 사람은 무엇이 화물이고 무엇이 밀항한 잡동사니인지 분간하기 어렵고, 배는 무거워지고 느려진다. 우리 제품 저장소는 대개 공개된 배다 — 처음 오르는 기여자가 딛는 갑판이다. 그 갑판에는 **이 배(제품)를 이해하고 함께 몰기 위해 필요한 것**만 싣는다. -## 제품 저장소에 두지 않는 것 +## 갑판에서 내리는 것 (offload) -- **인프라·운영(ops) 전용 도구** — 거버넌스 점검 스크립트, 배포·레지스트리 조작 등 특정 인프라에만 쓰이는 것. 개인 dotfiles나 private 운영 저장소로 분리한다. -- **AI 에이전트의 세션별 작업 노트·휘발성 컨텍스트·내부 히스토리 덤프.** -- **특정 사용자 환경에만 유효한 로컬 설정.** +- **인프라·운영(ops) 도구** — 거버넌스 점검 스크립트, 배포·레지스트리 조작 등 특정 항구에서만 쓰는 장비. 부두 창고(개인 dotfiles나 private 운영 저장소)에 둔다. +- **AI 에이전트의 세션별 항해 메모·휘발성 컨텍스트·내부 기록 덤프** — 지나간 물길에 남긴 낙서. +- **특정 선원의 손에만 맞는 로컬 설정.** -## 제품 저장소에 두는 것 (위 금지에 해당하지 않음) +## 배에 싣고 가는 것 (offload 대상 아님) -- **CI 워크플로·린트·포맷 설정** 등 저장소가 실제로 쓰는 자동화. -- **`CLAUDE.md`·`AGENTS.md`** 등 에이전트 작업 지침. 단 내용은 손으로 유지하지 말고 rutter가 렌더한 것(`pilot apply`)을 우선한다. -- **설계 결정 근거(ADR)·아키텍처 문서.** 이건 잡음이 아니라 제품의 **왜(Why)** 다 — [문서 작성 규약](documentation.md)의 정신과 같다. "context·history를 넣지 마라"가 설계 이유까지 지우는 쪽으로 해석되면 안 된다. +- **CI 워크플로·린트·포맷 설정** — 이 배가 실제로 쓰는 항해 장비다. +- **`CLAUDE.md`·`AGENTS.md`** 등 승무원(에이전트) 지침. 단 손으로 유지하지 말고 rutter가 렌더한 것(`pilot apply`)을 정본으로 삼는다. +- **설계 결정 근거(ADR)·아키텍처 문서 = 항해일지(logbook).** 이건 잡짐이 아니라 배가 왜 이 물길로 왔는지를 적은 기록이다 — [문서 작성 규약](documentation.md)의 **왜(Why)** 와 같은 것. "지나간 기록을 싣지 마라"가 항해일지까지 버리는 쪽으로 읽히면 안 된다. -## 판단 기준 +## 화물칸 앞에서의 물음 -한 파일이 위생 대상인지 헷갈리면 이렇게 묻는다 — **"이 저장소를 처음 보는 기여자가 제품을 이해하거나 기여하는 데 이게 필요한가?"** 필요하면 남기고, 특정 운영자·AI 세션·인프라에만 쓸모 있으면 밖으로 뺀다. +한 파일이 갑판에 있어도 되는지 헷갈리면 이렇게 묻는다 — **"이 배에 처음 오르는 사람이 제품을 이해하거나 함께 몰기 위해 이게 필요한가?"** 필요하면 싣고, 특정 항구·선원·세션에만 쓸모 있으면 부두에 내린다. From e5470c011c985a645f5b8fc2ebca14872742857a Mon Sep 17 00:00:00 2001 From: JeongUk Park Date: Sat, 25 Jul 2026 01:18:27 +0900 Subject: [PATCH 4/4] =?UTF-8?q?docs:=20=ED=8C=8C=EC=9D=BC=EB=AA=85?= =?UTF-8?q?=EC=9D=80=20=ED=95=AD=ED=95=B4=20=EC=BB=A8=EC=85=89(shipshape),?= =?UTF-8?q?=20=EB=82=B4=EC=9A=A9=EC=9D=80=20=ED=8F=89=EB=B2=94=ED=95=98?= =?UTF-8?q?=EA=B2=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/conventions/repo-hygiene.md | 23 ----------------------- docs/conventions/shipshape.md | 23 +++++++++++++++++++++++ 2 files changed, 23 insertions(+), 23 deletions(-) delete mode 100644 docs/conventions/repo-hygiene.md create mode 100644 docs/conventions/shipshape.md diff --git a/docs/conventions/repo-hygiene.md b/docs/conventions/repo-hygiene.md deleted file mode 100644 index 4f31df6..0000000 --- a/docs/conventions/repo-hygiene.md +++ /dev/null @@ -1,23 +0,0 @@ -# 저장소 위생 (repo hygiene) - -> **적용 범위**: 이 규약은 **제품 저장소**(대개 OSS로 공개되는 배)를 위한 것이다. 도구를 싣고 있는 private 운영 저장소는 이 규약의 *대상*이 아니라 잡짐을 옮겨 싣는 *부두 창고*다 — 자기가 실으라고 있는 화물을 버리라는 뜻이 아니다. 또한 이것은 사람·에이전트의 **판단형 항로 지침**이며, 기계 검증(PolicySet check)이 아니라 문서(convention)로 둔다. - -## Why - -배는 항해에 필요한 것만 싣는다. 갑판에 잡짐이 쌓이면 뒤따라 오르는 사람은 무엇이 화물이고 무엇이 밀항한 잡동사니인지 분간하기 어렵고, 배는 무거워지고 느려진다. 우리 제품 저장소는 대개 공개된 배다 — 처음 오르는 기여자가 딛는 갑판이다. 그 갑판에는 **이 배(제품)를 이해하고 함께 몰기 위해 필요한 것**만 싣는다. - -## 갑판에서 내리는 것 (offload) - -- **인프라·운영(ops) 도구** — 거버넌스 점검 스크립트, 배포·레지스트리 조작 등 특정 항구에서만 쓰는 장비. 부두 창고(개인 dotfiles나 private 운영 저장소)에 둔다. -- **AI 에이전트의 세션별 항해 메모·휘발성 컨텍스트·내부 기록 덤프** — 지나간 물길에 남긴 낙서. -- **특정 선원의 손에만 맞는 로컬 설정.** - -## 배에 싣고 가는 것 (offload 대상 아님) - -- **CI 워크플로·린트·포맷 설정** — 이 배가 실제로 쓰는 항해 장비다. -- **`CLAUDE.md`·`AGENTS.md`** 등 승무원(에이전트) 지침. 단 손으로 유지하지 말고 rutter가 렌더한 것(`pilot apply`)을 정본으로 삼는다. -- **설계 결정 근거(ADR)·아키텍처 문서 = 항해일지(logbook).** 이건 잡짐이 아니라 배가 왜 이 물길로 왔는지를 적은 기록이다 — [문서 작성 규약](documentation.md)의 **왜(Why)** 와 같은 것. "지나간 기록을 싣지 마라"가 항해일지까지 버리는 쪽으로 읽히면 안 된다. - -## 화물칸 앞에서의 물음 - -한 파일이 갑판에 있어도 되는지 헷갈리면 이렇게 묻는다 — **"이 배에 처음 오르는 사람이 제품을 이해하거나 함께 몰기 위해 이게 필요한가?"** 필요하면 싣고, 특정 항구·선원·세션에만 쓸모 있으면 부두에 내린다. diff --git a/docs/conventions/shipshape.md b/docs/conventions/shipshape.md new file mode 100644 index 0000000..025749c --- /dev/null +++ b/docs/conventions/shipshape.md @@ -0,0 +1,23 @@ +# 저장소 위생 (repo hygiene) + +> **적용 범위**: 이 규약은 **제품 저장소**(대개 OSS로 공개되는 것)를 위한 것이다. 도구를 호스팅하는 private 운영 저장소는 이 규약의 *대상*이 아니라 잡동사니를 옮겨 담는 *목적지*다 — 자기가 존재 이유인 도구를 비우라는 뜻이 아니다. 또한 이것은 사람·에이전트의 **판단형 가이드**이며, 기계 검증(PolicySet check) 대상이 아니라 문서(convention)로 둔다. + +## Why + +이 조직의 제품 저장소는 대부분 OSS로 공개된다. 제품과 무관한 잡동사니가 섞이면 기여자가 무엇이 제품이고 무엇이 노이즈인지 구분하기 어려워지고, 공개 저장소의 신호 대 잡음비가 떨어진다. 저장소는 "이 제품을 이해하고 기여하는 데 필요한 것"만 담아야 한다. + +## 제품 저장소에 두지 않는 것 + +- **인프라·운영(ops) 전용 도구** — 거버넌스 점검 스크립트, 배포·레지스트리 조작 등 특정 인프라에만 쓰이는 것. 개인 dotfiles나 private 운영 저장소로 분리한다. +- **AI 에이전트의 세션별 작업 노트·휘발성 컨텍스트·내부 히스토리 덤프.** +- **특정 사용자 환경에만 유효한 로컬 설정.** + +## 제품 저장소에 두는 것 (위 금지에 해당하지 않음) + +- **CI 워크플로·린트·포맷 설정** 등 저장소가 실제로 쓰는 자동화. +- **`CLAUDE.md`·`AGENTS.md`** 등 에이전트 작업 지침. 단 내용은 손으로 유지하지 말고 rutter가 렌더한 것(`pilot apply`)을 우선한다. +- **설계 결정 근거(ADR)·아키텍처 문서.** 이건 잡음이 아니라 제품의 **왜(Why)** 다 — [문서 작성 규약](documentation.md)의 정신과 같다. "context·history를 넣지 마라"가 설계 이유까지 지우는 쪽으로 해석되면 안 된다. + +## 판단 기준 + +한 파일이 위생 대상인지 헷갈리면 이렇게 묻는다 — **"이 저장소를 처음 보는 기여자가 제품을 이해하거나 기여하는 데 이게 필요한가?"** 필요하면 남기고, 특정 운영자·AI 세션·인프라에만 쓸모 있으면 밖으로 뺀다.