# 문서 재구조화 실행 현황 ## 목적 문서 중복/드리프트/탐색 난이도를 줄여, 에이전트가 문서 기반으로 기획/설계/구현/검증을 일관되게 수행하도록 운영 규칙을 고정한다. ## 적용 범위 - 루트 요약 문서: `README.md`, `CLAUDE.md` - 운영 문서: `docs/architecture.md`, `docs/commands.md`, `docs/testing.md`, `docs/workflow.md` - 실행 통제 문서군: `docs/ouroboros/*` - 검증 자동화: `scripts/validate_docs_sync.py`, CI 워크플로우 ## 완료 항목 (2026-03-01) ### 1) 문서 라우팅/역할 고정 - `docs/README.md` 신설 - 읽기 순서 + SSOT + 작성 규칙 명시 ### 2) 요약 문서 중복 축소 - `README.md`, `CLAUDE.md`에 문서 진입점 추가 - 가변 수치/세부 동작의 직접 중복 기재를 축약하고 SSOT 문서 링크 중심으로 정리 ### 3) 명령/테스트 문서 정합성 개선 - `docs/commands.md` 대시보드 API 목록 최신화(`pnl/history`, `positions` 포함) - `docs/testing.md` 테스트 총량 확인 방식을 고정 수치 -> `pytest --collect-only -q`로 전환 ### 4) 동기화 자동 검증 + CI 게이트 - `scripts/validate_docs_sync.py` 추가 - `.gitea/workflows/ci.yml`, `.github/workflows/ci.yml`에 `Validate docs sync` 단계 추가 - `docs/commands.md`에 동기화 검증 명령 추가 ## 잔여 작업 ### A) SSOT 강제 범위 확장 - `README.md`/`CLAUDE.md`의 남은 동작 설명을 더 축약하고 상세는 `docs/architecture.md`로 일원화 - `docs/testing.md`의 파일별 테스트 개수 스냅샷 자동 생성 여부 결정 ### B) 검증 규칙 고도화 - `validate_docs_sync.py`에 추가 패턴(중복 정책 문구/금지 숫자 표현) 확대 - 필요 시 `docs/architecture.md`를 API/모드 동작의 유일한 근거 문서로 명시 ### C) 유지보수 운영화 - 릴리즈/스프린트 종료 시 문서 동기화 점검 체크리스트 정례화 - 문서 변경 PR 템플릿에 "SSOT 링크 업데이트 여부" 체크박스 추가 검토 ## 검증 상태 - `python3 scripts/validate_docs_sync.py`: PASS - `python3 scripts/validate_ouroboros_docs.py`: PASS - `python3 scripts/validate_governance_assets.py`: PASS ## 운영 규칙 - 문서 구조 변경 시 `docs/README.md`와 동기화 검증 규칙을 함께 갱신한다. - 요약 문서는 "개요/진입점" 역할만 유지하고, 상세 사실/수치 정책은 SSOT 문서에만 기록한다. - 가변 수치(테스트 개수, 엔드포인트 개수)는 자동 확인 명령 또는 SSOT 링크로 대체한다. ## 참조 - 문서 허브: [docs/README.md](../../docs/README.md) - 실행 문서 허브: [docs/ouroboros/README.md](./README.md) - 동기화 검증 스크립트: [`scripts/validate_docs_sync.py`](../../scripts/validate_docs_sync.py)