Claude-51124 17cd0e34b4 docs: 구조화된 정보 형식 원칙 추가

- 표, 파일명:줄번호, 명확한 키워드 사용 권장
- JSON/XML 같은 기계적 형식 금지 명시
- AI와 사람 모두 읽기 좋은 구조화 원칙 추가

2025-12-06 18:04:09 +09:00

7.9 KiB

Raw Blame History

문서 작성 원칙

작성일: 2025-10-13 수정일: 2025-12-02 (CLAUDE.md → AGENTS.md 참조 변경) 참고: AGENTS.md, 311_FastAPI_구조_원칙.md

1. 문서 종류별 규칙

트러블슈팅 문서

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

주제별 파일 분리 (날짜 중복 허용)
시간순 작성
교훈 섹션 필수
100줄 이하 유지

필수 헤더:

# 제목

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

---

아키텍처 문서

경로: DOCS/300_architecture/ 파일명: 3NN_주제.md (예: 311_FastAPI_구조_원칙.md) 규칙:

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

계획 문서

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

규칙:

구현 완료 시 journey/troubleshooting/으로 이동 (필수)
구현 완료 섹션은 즉시 삭제 - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체
아키텍처/Phase/필요작업만 - 장황한 구현 코드 예시 최소화
시나리오/테스트/리포트 별도 파일 금지 - 하나의 파일에 통합
100줄 이하 유지

구분:

plans/: 미구현 계획만 (will do)
troubleshooting/: 구현 완료 + 문제 해결 (did + learned)

2. 작성 규칙

핵심 원칙 (최우선)

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

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

구조화된 정보 형식 (AI/사람 모두 읽기 좋게)

권장 형식:

표: 비교, 목록, 역할 구분 등 구조화된 정보 표현
파일명:줄번호: 코드 위치 명확히 참조
명확한 키워드: 검색 가능하도록 핵심 단어 명시
목록/부제목: 정보 계층 구조화

금지 형식:

JSON/XML 같은 기계적 형식 (사람이 읽기 어려움)
암호화된 코드나 해시값 직접 노출

절대 금지 사항

금지	이유
핵심 없는 장황한 설명, 중복 내용	핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체
쓸데없는 코드 작성 (전체 코드 블록)	파일명:줄번호만 명시
의사코드, 추측, 예측 ("아마", "것 같다")	확인된 사실만 기록
이모지 사용	명시적 요청 시만 허용
민감정보 직접 기록 (API 키, 비밀번호, JWT Secret Key, 토큰, DB 연결 정보 등)	보안 위험, 환경변수나 설정 파일로 분리하여 관리

파일 참조 형식

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

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

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

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


---

## 3. 문서 구조

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

```markdown
# 제목

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

---

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

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

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

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

아키텍처 문서 구조

# 제목

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

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

4. 파일 크기 제한

규칙

모든 문서: 100줄 이하
초과 시: 주제별 분리 또는 참고/실행용 분리

예외

아키텍처 문서: 200줄까지 허용 (섹션 많은 경우)
단, 분리 가능하면 분리 우선

5. 교훈 작성 규칙

필수 항목

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

올바른 예시

## 교훈

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

금지 예시

## 교훈

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

6. 비난조 문장 금지

금지 표현

"잘못 작성됨"
"버그가 많음"
"엉망진창"

권장 표현

"수정 필요"
"개선 가능"
"리팩토링 대상"

7. 체크리스트

문서 작성 전:

핵심만 간결하게 정리 (불필요한 설명/중복 제거, 링크로 대체)
파일명:줄번호로 위치 명시 (전체 코드 블록 금지)
확인된 사실만 기록 (추측/의사코드 제거)
파일명 형식 준수 (yymmdd_주제.md)
100줄 이하 확인
교훈 섹션 작성 (트러블슈팅)

문서 작성 후:

한 번 더 읽고 핵심 없는 부분/중복 제거

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

기능 개발 시 문서화 흐름

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

journey/scenarios/: UX 시나리오 작성 (만들기 전)
- 사용자 경험 관점에서 기능 정의
- "어떤 기능을 만들지" 먼저 정의
journey/plans/: 구현 계획 작성 (만들기 전)
- 아키텍처/Phase/필요작업만
- 구현 완료 시 troubleshooting/으로 이동
journey/troubleshooting/: 구현 과정 기록 (만들면서/만든 후)
- 문제 해결, 교훈, 테스트 결과
- 하나의 파일에 통합 (시나리오/테스트/리포트 별도 파일 금지)
서비스 README.md: 핵심 사항 업데이트 (만든 후)
- 엔드포인트, 환경변수, 사용 방법
- 자주 변하는 구체적 정보
book/: 원칙 변경 시 업데이트 (필요시)
- 아키텍처 원칙이 바뀌면 반영
- guidelines/에 개발 가이드라인 추가/수정
AGENTS.md: 개발 원칙/운영 규칙 변경 시 업데이트 (필요시)
- 새로운 작업 규칙이 생기면 반영

문서 역할 구분

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

Journey 내부 흐름

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

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

9. 참고 문서

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

7.9 KiB Raw Blame History