From 6f75392ddc52a66aa69e5afc962c4f867716a78d Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Sat, 3 Jan 2026 12:40:59 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EB=AC=B8=EC=84=9C=20=EC=9E=91=EC=84=B1?= =?UTF-8?q?=20=EC=9B=90=EC=B9=99=20=EC=A4=91=EB=B3=B5=20=EC=A0=9C=EA=B1=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 크기 제한: 각 문서 종류별 규칙에서 반복 제거, 섹션 4로 참조 통일 - 중복 작성 금지: 핵심 원칙에 통합, 나머지에서 참조 - 파일명:줄번호: 파일 참조 형식 섹션으로 통합, 체크리스트에서 참조 - 초과 시 처리: 표 비고 간소화, 상세는 섹션 4에만 유지 - 체크리스트: 구체적 내용 제거, 섹션 참조로 통일 --- .../312_문서_작성_원칙.md | 35 ++++++++----------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/book/300_architecture/312_문서_작성_원칙.md b/book/300_architecture/312_문서_작성_원칙.md index 035ecbe..1f52350 100644 --- a/book/300_architecture/312_문서_작성_원칙.md +++ b/book/300_architecture/312_문서_작성_원칙.md @@ -16,7 +16,7 @@ - 주제별 파일 분리 (날짜 중복 허용) - 시간순 작성 - 교훈 섹션 필수 -- 100줄 이하 유지 +- 크기 제한: 섹션 4 참조 **필수 헤더**: ```markdown @@ -50,7 +50,7 @@ - **구현 완료 섹션은 즉시 삭제** - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체 - **아키텍처/Phase/필요작업만** - 장황한 구현 코드 예시 최소화 - **Phase별 분리 가능**: 복잡한 계획은 Phase 1/2/3으로 분리 가능 -- 100줄 이하 유지 (Phase별 분리 시 각 파일 100줄 이하) +- 크기 제한 및 초과 시 처리: 섹션 4 참조 **구분**: - `plans/`: 미구현 계획만 (will do) @@ -66,9 +66,9 @@ **규칙**: - **인덱스/목차 역할만** - 문서 목록과 간단한 설명 - **상세 내용은 링크로 참조** - 트러블슈팅, 계획 등 실제 문서로 링크 -- **중복 작성 금지** - 상세 내용을 README에 다시 작성하지 않음 - **핵심 키워드만** - 각 문서의 핵심만 간단히 나열 -- 100줄 이하 유지 +- 중복 작성 금지: 섹션 2 핵심 원칙 참조 +- 크기 제한: 섹션 4 참조 **예시**: ```markdown @@ -78,10 +78,7 @@ - 개선: 제로샷 임베딩 70.2% (+46.8%p) ``` -**금지**: -- 트러블슈팅 문서의 상세 내용을 README에 다시 작성 -- 구현 코드나 테스트 결과 상세 재현 -- troubleshooting 문서의 "교훈" 섹션 전체 복사 +**금지 사례**: 상세 내용 재작성, 코드/테스트 결과 상세 재현, "교훈" 섹션 전체 복사 --- @@ -92,8 +89,7 @@ **"핵심만 간결하게 정리"** - 문서의 모든 내용은 이 원칙을 준수해야 함 - 불필요한 설명, 중복 내용, 장황한 문장 제거 - 필요한 정보만 간결하게 기록 -- 관련 정보는 링크로 참조 (중복 작성 금지) -- **같은 내용인 경우 새로운 파일 생성하지 말고 기존 파일 수정하여 깔끔하게 정리** +- 관련 정보는 링크로 참조 (중복 작성 금지, 같은 내용이면 새 파일 생성하지 말고 기존 파일 수정) ### 구조화된 정보 형식 (AI/사람 모두 읽기 좋게) @@ -111,8 +107,8 @@ | 금지 | 이유 | |------|------| -| 핵심 없는 장황한 설명, 중복 내용 | 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체 | -| 쓸데없는 코드 작성 (전체 코드 블록) | 파일명:줄번호만 명시 | +| 핵심 없는 장황한 설명 | 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체 | +| 전체 코드 블록 | 파일명:줄번호만 명시 (파일 참조 형식 섹션 참조) | | 의사코드, 추측, 예측 ("아마", "것 같다") | 확인된 사실만 기록 | | 이모지 사용 | 명시적 요청 시만 허용 | | 민감정보 직접 기록 (API 키, 비밀번호, JWT Secret Key, 토큰, DB 연결 정보 등) | 보안 위험, 환경변수나 설정 파일로 분리하여 관리 | @@ -194,8 +190,7 @@ ### 초과 시 처리 방법 **트러블슈팅 문서**: -- 단일 이슈 중심으로 유지, 핵심만 간결하게 -- 초과 시: 불필요한 설명/중복 제거 또는 주제별 분리 +- 단일 이슈 중심, 핵심만 간결하게 (초과 시 불필요한 설명/중복 제거 또는 주제별 분리) **계획 문서**: - Phase 1/2/3으로 단계별 분리 가능 @@ -256,15 +251,15 @@ ## 7. 체크리스트 문서 작성 전: -- [ ] **핵심만 간결하게 정리** (불필요한 설명/중복 제거, 링크로 대체) -- [ ] 파일명:줄번호로 위치 명시 (전체 코드 블록 금지) +- [ ] **핵심만 간결하게 정리** (섹션 2 핵심 원칙 참조) +- [ ] 파일명:줄번호로 위치 명시 (섹션 2 파일 참조 형식 참조) - [ ] 확인된 사실만 기록 (추측/의사코드 제거) - [ ] 파일명 형식 준수 (yymmdd_주제.md) -- [ ] 문서 유형별 크기 제한 확인 (트러블슈팅/계획: 100줄, 리서치/아키텍처: 200줄) -- [ ] 교훈 섹션 작성 (트러블슈팅) +- [ ] 문서 유형별 크기 제한 확인 (섹션 4 참조) +- [ ] 교훈 섹션 작성 (트러블슈팅, 섹션 5 참조) 문서 작성 후: -- [ ] 한 번 더 읽고 핵심 없는 부분/중복 제거 +- [ ] 한 번 더 읽고 핵심 없는 부분/중복 제거 (섹션 2 핵심 원칙 참조) --- @@ -284,7 +279,7 @@ 3. **`journey/troubleshooting/`**: 구현 과정 기록 (만들면서/만든 후) - 문제 해결, 교훈, 테스트 결과 - - 단일 이슈 중심으로 통합 (관련 이슈는 하나의 파일에, 초과 시 주제별 분리) + - 크기 제한 및 초과 시 처리: 섹션 4 참조 4. **서비스 README.md**: 핵심 사항 업데이트 (만든 후) - 엔드포인트, 환경변수, 사용 방법