Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/conventions/shipshape.md
Original file line number Diff line number Diff line change
@@ -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 세션·인프라에만 쓸모 있으면 밖으로 뺀다.
Loading