jihoson/The-Ouroboros

Fork 0

Files

agentson 4ca582b418

Gitea CI / test (push) Failing after 3s

Details

Gitea CI / test (pull_request) Failing after 3s

Details

docs: SSOT 문서 허브 도입 및 동기화 자동 검증 게이트 (#350 )

문서 중복·드리프트를 구조적으로 방지하기 위해 SSOT 원칙을 문서 체계에 적용한다.

신규:
- docs/README.md: 문서 라우팅/역할/읽기 순서/SSOT 정의 (상대경로 링크)
- scripts/validate_docs_sync.py: 가변 수치 하드코딩 금지 + 누락 엔드포인트 검사

수정:
- CLAUDE.md: 문서 진입점 추가, SmartScanner 세부 동작 → architecture.md 링크
- README.md: 문서 네비게이션 섹션 추가, 고정 수치/파일별 케이스 수 제거
- docs/commands.md: validate_docs_sync.py 명령 추가; 중복 엔드포인트 2행 제거
- docs/testing.md: 테스트 총량 고정값 → pytest --collect-only -q 동적 확인으로 전환
- docs/ouroboros/82_doc_restructure_plan.md: draft → active, 실행 현황으로 전환
- .gitea/PULL_REQUEST_TEMPLATE.md: Docs Sync 체크리스트 추가
- .gitea/workflows/ci.yml + .github/workflows/ci.yml: validate_docs_sync 단계 추가

검증:
- python3 scripts/validate_docs_sync.py: PASS

Closes #350

2026-03-01 17:07:59 +09:00

2.8 KiB

Raw Blame History

문서 재구조화 실행 현황

목적

문서 중복/드리프트/탐색 난이도를 줄여, 에이전트가 문서 기반으로 기획/설계/구현/검증을 일관되게 수행하도록 운영 규칙을 고정한다.

적용 범위

루트 요약 문서: 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/ouroboros/README.md
동기화 검증 스크립트: scripts/validate_docs_sync.py

2.8 KiB Raw Blame History