happybell80 586a7493fc docs: global-principles→헌장 링크 수정 + 절대경로→GitHub URL 정합 + 스킬 SKILL.md 추가

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Made-with: Cursor

2026-03-30 00:17:29 +09:00

17 KiB

Raw Permalink Blame History

문서 작성 원칙

작성일: 2025-10-13 수정일: 2026-03-05 (SSOT 관리 기준 명시) 참고: AGENTS.md, 311_backend_coding_principles.md 상위 원칙: 0_VALUE Writing Principles

0. SSOT 관리 기준

문서 작성 상세 원칙의 SSOT는 본 문서(312_writing-principles.md)다.
상위 공통 원칙의 SSOT는 0_VALUE/20_Governance/writing-principles.md다.
본 문서는 robeing 프로젝트에 필요한 구체화 문서다.
원칙 충돌 시 상위 원칙을 먼저 검토하고, 예외가 필요하면 사용자에게 먼저 보고한 뒤 본 문서에 예외를 기록한다.
하위 폴더 README.md와 개별 문서는 원칙 본문을 반복하지 않고 SSOT 링크만 둔다.
상위 원칙 링크는 문서를 해석하는 데 직접 필요한 최소 SSOT만 둔다. 관련 없는 원칙 문서를 관성적으로 모두 나열하지 않는다.
동일 원칙을 여러 문서에 복제하지 않는다. 필요 시 본 문서를 수정하고 참조 링크만 갱신한다.
실행/코드 정책(예: 폴백·예외 처리 최소화, 원인 경로 직접 수정)은 AGENTS.md를 SSOT로 본다.
본 문서의 리서치/시나리오 원칙은 문서화 표현 기준이며, 코드 동작 정책을 대체하지 않는다.

1. 문서 종류별 규칙

트러블슈팅 문서

경로: DOCS/journey/troubleshooting/ 파일명: yymmdd_주제.md (예: 251013_coldmail_ir_analyzer_fix.md) 규칙:

주제별 파일 분리 (날짜 중복 허용)
시간순 작성
교훈 섹션 필수
크기 제한: 섹션 4 참조
⚠️ 절대 금지: 남은 작업 기록 - 남은 작업을 troubleshooting 문서에 기록하면 다음 작업 시 계획이 어수선해짐. 남은 작업은 반드시 plans/ 문서의 "남은 작업" 섹션에만 기록

필수 헤더:

# 제목

**날짜**: 2025-10-13
**작성자**: happybell80
**관련 파일**: `경로/파일명.py`

---

아키텍처 문서

경로: DOCS/300_architecture/ 파일명: 3NN_주제.md (예: 311_backend_coding_principles.md) 규칙:

작성일/수정일 명시
섹션 번호 사용
표, 다이어그램 권장
코드 예시 (올바름/금지) 포함

계획 문서

경로: DOCS/journey/plans/ 파일명: yymmdd_주제.md 용도: 미래 계획, 아이디어만 (아직 구현 안 됨)

규칙 (⚠️ 핵심 원칙 - 절대 위반 금지):

구현 완료 시 즉시 journey/plans/archive/로 이동 (필수, 지연 금지) - plans/에는 미구현 계획만 남김
모든 구현 완료 섹션은 즉시 삭제 - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체 (상세 완료 사항 나열 금지)
배포/테스트 완료 후 바로 archive 이동 - troubleshooting 문서 작성과 동시에 또는 그 직후 즉시 처리
구현 코드 파일 금지 - SQL 마이그레이션 파일(.sql), 코드 파일(.py, .js 등) 등 실제 구현 파일은 plans/에 두지 않고 해당 서비스 코드베이스에 위치
명확한 행동강령만 기록 - 불확실한 표현("예상", "가능", "고려", "검토", "추후", "나중", "필요시", "선택", "옵션", "또는", "아마", "것 같", "추정") 금지
여지가 있는 내용은 아이디어 폴더로 이동 - 불확실한 아이디어는 journey/ideas/에 기록
아키텍처/Phase/필요작업만 - 장황한 구현 코드 예시 최소화
Phase별 분리 가능: 복잡한 계획은 Phase 1/2/3으로 분리 가능
크기 제한 및 초과 시 처리: 섹션 4 참조

부분 완료 문서 처리 (⚠️ 핵심 원칙):

부분 완료 문서는 plans/에 유지 - 전체 완료 시에만 archive로 이동
완료된 섹션은 삭제하고 troubleshooting 링크로만 대체 - "→ 상세: troubleshooting/yymmdd_*.md" 형식 (상세 완료 사항 나열 금지)
미구현 항목만 "남은 작업" 섹션에 남기기 - 아키텍처/Phase/필요작업만 기록

구분 (⚠️ 명확히 구분 필수):

plans/: 미구현 계획만 (will do) - 부분 완료 포함, 구현 완료 섹션 절대 금지, 남은 작업 기록 위치
plans/archive/: 전체 구현 완료된 계획 (참고용 보관)
troubleshooting/: 구현 완료 + 문제 해결 (did + learned), 남은 작업 기록 절대 금지 (남은 작업을 troubleshooting에 기록하면 다음 작업 시 계획이 어수선해짐)

인덱스 README.md

경로: DOCS/journey/research/, DOCS/journey/ideas/ 등 폴더 내부 파일명: README.md 용도: 해당 폴더의 문서 인덱스 및 목차 역할

규칙:

인덱스/목차 역할만 - 문서 목록과 간단한 설명
문서 목록은 클릭 가능한 링크 - 백틱 경로(파일명.md) 대신 [제목](경로) Markdown 링크 사용 (상위 원칙 §4 링크 표준)
상세 내용은 링크로 참조 - 트러블슈팅, 계획 등 실제 문서로 링크
핵심 키워드만 - 각 문서의 핵심만 간단히 나열
README 본문 상세 금지 - 상태/목표/필요작업/결론의 상세 본문은 원문 문서에만 작성
README 중복 금지 - 특정 계획 문서의 본문 3~5줄 요약 템플릿(상태/목표/참고)을 반복 복사하지 않음
중복 작성 금지: 섹션 2 핵심 원칙 참조
크기 제한: 섹션 4 참조

예시:

## 성능 비교 테스트
- [하이브리드 의도 분류 성능 비교](../troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md)
  - 초기: FastPath 49.6%, 제로샷 임베딩 23.4%
  - 개선: 제로샷 임베딩 70.2% (+46.8%p)

금지 사례: 상세 내용 재작성, 코드/테스트 결과 상세 재현, "교훈" 섹션 전체 복사

아이디어 문서

경로: DOCS/journey/ideas/ 규칙:

미구현 아이디어만 유지: 구현 결과가 troubleshooting·plans에 정리되면 ideas 문서 삭제(또는 deprecated/로 이동)
핵심만 기록: 간단한 흐름·배경만 남기고 상세 구현 내용은 계획/트러블슈팅으로 이동

리서치 문서

경로: DOCS/journey/research/ 규칙:

원인 확정이 해결안 제시보다 우선이다.
원인 분석 정확도 목표는 100%로 둔다. 불확실하면 "미확정"으로 기록한다.
해결 포인트는 단일 경로로 좁히고, 비대상 프로젝트 영향은 0을 기준으로 분리한다.
사실/해석/결론을 분리해 기록한다.
출처 URL(또는 내부 문서 경로)과 확인 시점을 명시한다.
구현 코드 복붙 대신 파일 경로·핵심 위치 참조를 사용한다.
문서명과 본문 상태에 종료, 종결, 완료를 쓰지 않는다. 리서치는 방향/원인/근거를 확정하는 단계이고, 닫힘 선언은 worklog 또는 문제 문서 상태에서만 한다.
README에는 원칙 본문을 반복하지 않고, 본 섹션(SSOT) 링크만 둔다.

시나리오 문서

경로: DOCS/journey/scenarios/ 규칙:

문서 상단에 상태: 완료 / 부분 / 미구현을 명시
구현 완료 시 대응되는 troubleshooting·plans 링크를 함께 표기
UX 흐름만 기록하고 내부 구현 세부 설명은 링크로 참조
사용자/운영자 행동 기준으로 작성 (누가, 언제, 무엇을 하려다, 어디서 막히는지)
기술 용어보다 체감 결과를 우선 기록 (기다림, 재시도, 업무 지연, 실행 실패)
한 문서는 반드시 문제 → 문제 상황(현재 체감) → 해결 후 기대 상황 3축으로 쓴다.
실패 장면 1개와 개선 후 장면 1개를 같은 맥락으로 짝지어 기록한다.

시나리오 핵심 원칙(요약):

사용자(인간) 시점으로 쓴다.
기술 설명보다 체감 불편을 먼저 쓴다.
해결 뒤 달라질 상태를 명확히 쓴다.

2. 작성 규칙

핵심 원칙 (최우선)

"핵심만 간결하게 정리" - 문서의 모든 내용은 이 원칙을 준수해야 함

불필요한 설명, 중복 내용, 장황한 문장 제거
필요한 정보만 간결하게 기록
관련 정보는 링크로 참조 (중복 작성 금지, 같은 내용이면 새 파일 생성하지 말고 기존 파일 수정)

링크 작성 원칙 (필수)

공통 규칙은 0_VALUE/20_Governance/writing-principles.md §4 참조.

출처 표기 방법

출처는 요약문에 하이퍼링크를 거는 형식으로 표기합니다.
형식: [요약문](URL) — 요약문을 클릭하면 해당 URL로 이동합니다.
예시:
- [Pardon? 같은 영어 표현 소개(스피킹스튜디오)](https://www.instagram.com/p/DSGp0eRjjmD/)
- [영어 표현 12개를 배우는 회화 영상](https://www.youtube.com/watch?v=QneqFpTsQzo)
- [직장인영어회화 '다시 한번 말씀해 주시겠어요?'(되묻기 pardon)](https://m.blog.naver.com/yanadooblog/221588091601)

절대 금지 사항

금지	이유
핵심 없는 장황한 설명	핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체
전체 코드 블록	파일명:줄번호만 명시 (파일 참조 형식 섹션 참조)
의사코드, 추측, 예측 ("아마", "것 같다")	확인된 사실만 기록
이모지 사용	명시적 요청 시만 허용
민감정보 직접 기록 (API 키, 비밀번호, JWT Secret Key, 토큰, DB 연결 정보 등)	보안 위험, 환경변수나 설정 파일로 분리하여 관리
troubleshooting 문서에 남은 작업 기록	다음 작업 시 계획이 어수선해짐, 남은 작업은 반드시 `plans/` 문서에 기록

파일 참조 형식

올바름 (파일명:줄번호 + 간단 설명):

- naverworks_briefing.py:58-74: 폴백 제거
- ir_analyzer.py:28: /api/query → /api/search

금지 (전체 코드 복사, 추상적 표현):

- naverworks_briefing.py에서 폴백 제거  ← 구체적 위치 없음
- ir_analyzer.py 파일 수정  ← 구체적 내용 없음
```python
# 전체 함수 코드 50줄 복사...  ← 불필요


---

## 3. 문서 구조

### 트러블슈팅 문서 구조

```markdown
# 제목

**날짜**, **작성자**, **관련 파일**

---

## 문제 상황
- 현상, 에러 메시지

## 해결 방안
- 파일명:줄번호 명시
- 수정 내용 간결히

## 구현 완료 (선택)
- 커밋 해시, 날짜

## 교훈 (필수)
- 왜 발생했는가
- 다음에 어떻게 방지할 것인가

⚠️ **절대 금지**: "남은 작업" 섹션 추가 금지. 남은 작업은 반드시 `plans/` 문서에 기록

아키텍처 문서 구조

# 제목

**작성일**: 2025-10-13
**수정일**: 2025-10-13 (수정 이유)

## 1. 원칙
## 2. 규칙
## 3. 예시
## 4. 체크리스트
## 5. 참고

시나리오 문서 구조

필수 섹션 3개: 문제 / 문제 상황(현재 체감) / 해결 후 기대 상황
필수 장면 2개: 실패 장면 1개 / 개선 후 장면 1개
연결 문서: troubleshooting/plans/research 링크만 첨부 (구현 상세 복붙 금지)

4. 파일 크기 제한

문서 유형별 크기 제한

문서 유형	크기 제한	비고
트러블슈팅 문서	150줄 이하	단일 이슈 중심, 초과 시 주제별 분리
계획 문서	200줄 이하	Phase별로 분리 가능
인덱스 README.md	150줄 이하	목차/인덱스 역할만
리서치 문서	250줄 이하	논문 요약 등 긴 내용 허용
아키텍처 문서	250줄 이하	섹션 많은 경우, 분리 가능하면 분리 우선

초과 시 처리 방법

트러블슈팅 문서:

단일 이슈 중심, 핵심만 간결하게 (초과 시 불필요한 설명/중복 제거 또는 주제별 분리)

계획 문서:

Phase 1/2/3으로 단계별 분리 가능
또는 관련 troubleshooting 문서로 링크

리서치/아키텍처 문서:

분리 가능하면 주제별 섹션 분리
또는 관련 문서로 링크 참조

기존 문서 처리

기존 100줄 초과 문서는 과도적 예외로 인정
신규 작성 시부터 위 원칙 적용
기존 문서 수정 시 가능하면 원칙 준수하도록 간소화 권장

5. 교훈 작성 규칙

필수 항목

원인: 왜 문제가 발생했는가
교훈: 다음에 어떻게 방지할 것인가
원칙: 위반한 원칙이 있는가 (원칙 문서 참조: 311_backend_coding_principles.md, 312_writing-principles.md)

올바른 예시

## 교훈

### API 엔드포인트 검증 부족
- 구현 시 skill-rag-file API 스펙 미확인
- 추측으로 /api/query 사용, 실제는 /api/search
- 교훈: 스킬 통합 전 API 문서 또는 코드 직접 확인 필수

금지 예시

## 교훈

에러가 발생했습니다. 다음에 조심하겠습니다.

6. 표현/문체 원칙

공통 규칙은 0_VALUE/20_Governance/writing-principles.md §7 참조.

7. 체크리스트

문서 작성 전:

핵심만 간결하게 정리 (섹션 2 핵심 원칙 참조)
파일명:줄번호로 위치 명시 (섹션 2 파일 참조 형식 참조)
확인된 사실만 기록 (추측/의사코드 제거)
파일명 형식 준수 (yymmdd_주제.md)
문서 유형별 크기 제한 확인 (섹션 4 참조)
교훈 섹션 작성 (트러블슈팅, 섹션 5 참조)
troubleshooting 문서 작성 시: 남은 작업 섹션 추가 금지 (남은 작업은 반드시 plans/ 문서에 기록)

문서 작성 후:

한 번 더 읽고 핵심 없는 부분/중복 제거 (섹션 2 핵심 원칙 참조)
troubleshooting 문서 검토: "남은 작업" 섹션이 있다면 삭제하고 plans/ 문서로 이동

원칙 실행 시: 선택적 독해·단계 압축 방지

원칙을 실행할 때 다음을 반드시 지킨다.

체크리스트 강제 실행: 해당 문서(예: 312 본문 270~276줄)의 체크리스트를 작업 시작 전에 읽고, 각 항목을 순서대로 확인한 뒤 실행한다. 사용자 지시(예: "푸시해")만 보고 단계를 건너뛰지 않는다.
키워드 검색 후 전체 문장 읽기: 원칙에서 키워드(예: "archive 이동")를 찾았으면 해당 줄만 보지 말고, 앞뒤 3줄을 포함해 조건절(예: "troubleshooting 문서 작성과 동시에")이 있는지 확인한 뒤 실행한다.
완료 조건 명시적 확인: "완료"라고 판단하기 전에, 해당 원칙에서 완료의 정의(필수 단계 목록)를 찾아 누락 단계가 없는지 확인한 뒤 완료 처리한다.

8. 개발 과정에서 문서 정리 원칙

기능 개발 시 문서화 흐름

새로운 기능을 만들 때 다음 순서로 문서를 작성/업데이트합니다:

journey/scenarios/: UX 시나리오 작성 (만들기 전)
- 사용자 경험 관점에서 기능 정의
- "어떤 기능을 만들지" 먼저 정의
계획 문서 (journey/plans/): 구현 계획 작성 (만들기 전)
- 아키텍처/Phase/필요작업만 기록 (섹션 1 참조)
- 구현 완료 시 plans/archive/로 이동하고 troubleshooting 문서와 링크 연결
트러블슈팅 문서 (journey/troubleshooting/): 구현 과정 기록 (만들면서/만든 후)
- 문제 해결, 교훈, 테스트 결과 기록 (섹션 1 참조)
- 크기 제한 및 초과 시 처리: 섹션 4 참조
- ⚠️ 절대 금지: 남은 작업 기록 - 남은 작업은 반드시 plans/ 문서에 기록
서비스 README.md: 서비스별 핵심 사항 업데이트 (만든 후)
- 엔드포인트, 환경변수, 사용 방법 등 구체적 정보 기록
인덱스 README.md: 폴더별 문서 인덱스 업데이트 (만든 후)
- 문서 목록과 간단한 설명 기록 (섹션 1 참조)
book/: 원칙 변경 시 업데이트 (필요시)
- 아키텍처 원칙이 바뀌면 반영
- guidelines/에 개발 가이드라인 추가/수정
AGENTS.md: 개발 원칙/운영 규칙 변경 시 업데이트 (필요시)
- 새로운 작업 규칙이 생기면 반영

문서 역할 구분

문서 종류	역할	변경 빈도
`book/`	항상성, 원칙, 철학	거의 변하지 않음
`journey/`	진화 과정 (scenarios → ideas → research → plans → troubleshooting)	계속 추가됨
서비스 README.md	현재 상태 (포트, 엔드포인트, 환경변수)	자주 변함
인덱스 README.md (research/, ideas/ 등)	문서 목차/인덱스, 상세는 링크 참조	새 문서 추가 시
`AGENTS.md`	개발자별 룰, 운영 규칙	필요시 변경

Journey 내부 흐름

scenarios/ (UX 정의)
    ↓
ideas/ (아이디어 탐색)
    ↓
research/ (이론적 기반)
    ↓
plans/ (구현 계획)
    ↓
troubleshooting/ (실제 구현)

참고: 각 단계는 필수가 아니며, 필요에 따라 생략 가능

9. 참고 문서

AGENTS.md: 전체 개발 가이드
311_backend_coding_principles.md: 코드 구조 원칙
troubleshooting/ 폴더: 트러블슈팅 예시

17 KiB Raw Permalink Blame History