풀뿌리 문서 관리 규칙

버전: 2.0 | 최종 업데이트: 2026-01-29

핵심 원칙

개요 파일은 가볍게, 상세는 개별 파일로 세분화

개요/인덱스 파일 → 1~3줄 설명 + 파일명/위치 참조만
상세 파일       → 종류별, 기능별로 각각 독립 파일

1. 파일 유형별 역할

2. 개요/인덱스 파일 규칙

포함해야 할 것

• 각 섹션/하위 폴더의 1~3줄 요약
• 상대 경로 참조 링크 (→ 상세: 파일명 형식)
• 전체 구조를 한눈에 파악할 수 있는 간단한 표 또는 목록

포함하지 말 것

• 큰 ASCII 다이어그램 (상세 파일로 이동)
• 명령어 전체 목록 (레퍼런스 파일로 분리)
• 단계별 상세 설명 (상세 파일로 분리)
• 코드 블록 (3줄 이내 짧은 예시만 허용)

참조 링크 형식

→ 상세: [`파일명.md`](상대경로/파일명.md)
→ 상세: [`폴더명/`](상대경로/폴더명/)

3. 상세 파일 규칙

단일 책임

• 하나의 파일은 하나의 주제만 다룬다
• 파일명으로 내용을 즉시 파악할 수 있어야 한다

분리 기준

• 2개 이상의 독립적 주제가 포함된 경우
• 큰 다이어그램/표가 3개 이상인 경우
• 목차가 3단계 이상 깊어지는 경우

4. 네이밍 컨벤션

5. 신규 문서 추가 체크리스트

새 문서를 추가할 때 확인:

• 기존 파일에 내용 추가로 해결 가능한가? → 가능하면 신규 파일 생성 금지
• 적절한 폴더에 위치하는가?
• 네이밍 컨벤션을 따르는가?
• 상위 인덱스/README에 참조 링크를 추가했는가?
• 단일 책임 원칙을 지키는가? (하나의 주제만)
• 내용이 비대하지 않은가? (비대하면 분할)

6. 기존 문서 수정 시 체크리스트

• 상세 내용을 개요 파일에 인라인하지 않았는가?
• 개요 파일에 추가한 내용이 5줄 이내 요약인가?
• 참조 링크가 실제 파일과 일치하는가?
• 수정 후 파일이 비대해지지 않았는가?

7. 안티 패턴

하지 말 것

이 규칙은 01-dev-rules-system/ 내 모든 문서에 적용됩니다. 프로젝트의 docs/ 폴더에도 동일한 원칙을 권장합니다.

← 체계 목차