콘텐츠로 이동

Repository Guidelines

프로젝트 구조와 모듈 구성

이 저장소는 전통적인 앱이 아니라 LLM이 유지보수하는 Markdown 위키로 확장될 예정입니다. 현재 핵심 개념은 llm-wiki.md에 정리되어 있습니다. 저장소가 커질수록 아래의 세 계층 구조를 유지합니다.

  • raw/: 클리핑한 글, PDF, 이미지 같은 변경하지 않는 원본 자료
  • wiki/: 생성된 지식 페이지, 엔티티 페이지, 주제 요약, 비교 문서
  • 저장소 루트: AGENTS.md, index.md, log.md 같은 제어 파일

index.md는 탐색용 카탈로그로, log.md는 append-only 운영 기록으로 다룹니다. log.md 항목 형식은 docs/log-maintenance.md를 따릅니다. 운영 문서 허브는 docs/README.md에 정리합니다. 실제 프로젝트 문서를 위키 도메인 묶음으로 확장하는 기준은 docs/domain-ingest-pattern.md에 정리합니다.

빌드, 테스트, 개발 명령

아직 정식 빌드 파이프라인은 없습니다. 대신 아래 같은 가벼운 로컬 점검 명령을 사용합니다.

  • rg --files . : 추적 중인 콘텐츠 파일 목록 확인
  • grep "^## \\[" log.md | tail -5 : 최신 로그 항목 확인
  • git diff --stat : 커밋 전 위키 변경 범위 확인
  • python3 scripts/generate_index_draft.py : index.md 자동 관리 섹션 초안 생성
  • python3 scripts/check_index_sync.py : 현재 index.md 관리 섹션과 wiki/ frontmatter 동기화 검사
  • python3 scripts/find_term_candidates.py : 현재 위키 문서에서 독립 문서로 확장할 용어 후보 추천
  • python3 scripts/find_term_candidates.py --include-docs --limit 20 : 운영 backlog 문서까지 포함해 확장 후보 용어 추천
  • python3 scripts/find_term_candidates.py --write --include-docs --limit 20 : 후보 backlog 문서 docs/term-expansion-candidates.md 갱신
  • python3 scripts/run_ci_checks.py : 기본 구조 검증과 테스트 명령을 CI 순서대로 한 번에 실행
  • make verify : 로컬과 CI에서 공통으로 쓰는 기본 검증 진입점
  • make web-build : MkDocs 정적 사이트를 site/ 디렉터리에 빌드
  • make web-serve : MkDocs 로컬 미리보기 서버 실행
  • make web-stage : MkDocs용 staging 디렉터리 .mkdocs-docs/ 생성
  • python3 -m pip install -r requirements.txt : 웹 공개용 MkDocs 의존성 설치
  • python3 scripts/stage_mkdocs_docs.py : 루트 문서, docs/, wiki/, raw/를 MkDocs staging 디렉터리로 복사
  • python3 -m mkdocs build : 웹 배포용 정적 산출물 생성
  • python3 -m mkdocs serve : 웹 문서 로컬 미리보기 서버 실행
  • python3 scripts/verify_wiki.py : log.md 형식, frontmatter, 상대 경로 링크, raw_source, raw/source 대응성, source freshness, 도메인 묶음 완결성, 고아 문서, index.md 동기화를 한 번에 검사
  • python3 -m unittest tests.test_generate_index_draft -v : 인덱스 초안 생성기 테스트 실행
  • python3 -m unittest tests.test_check_index_sync -v : 인덱스 동기화 검사기 테스트 실행
  • python3 -m unittest tests.test_find_term_candidates -v : 용어 후보 추출기 테스트 실행
  • python3 -m unittest tests.test_verify_wiki -v : 통합 위키 검증 스크립트 테스트 실행
  • python3 -m unittest tests.test_run_ci_checks -v : CI 검증 러너 테스트 실행

나중에 도구를 추가하더라도, 명령은 이 문서에 기록하고 저장소 로컬 기준의 단순한 워크플로를 우선합니다.

코딩 스타일과 네이밍 규칙

문서는 Markdown으로 작성하고, 제목은 짧고 설명적으로 유지합니다. 섹션 제목은 특별한 이유가 없으면 문장형 표기를 따릅니다. 파일명은 topic-summary.md, entity-alan-kay.md처럼 소문자 kebab-case를 권장합니다.

페이지 사이 링크는 상대 경로 Markdown 링크를 사용합니다. raw/ 아래 파일은 변경하지 않고, wiki/의 생성 문서를 수정한 경우 index.md와 log.md도 같은 변경 단위에서 함께 갱신합니다.

wiki/ 아래 문서는 YAML frontmatter를 사용합니다. 기본 필드는 title, type, status, updated, tags이며, 소스 요약은 raw_source, 템플릿은 template_for를 추가할 수 있습니다. type에는 synthesis도 포함하며, 스키마 세부 규칙은 docs/frontmatter-schema.md에 정리합니다.

index.md는 frontmatter를 기준으로 유지합니다. 소스, 엔티티, 개념, 비교 및 분석, 합성 문서, 템플릿 섹션 배치와 정렬 규칙은 docs/index-maintenance.md를 따릅니다. log.md는 docs/log-maintenance.md의 헤더/필수 줄 규칙을 따릅니다. 검증 범위와 실패 기준은 docs/verification-rules.md에 정리합니다.

테스트 가이드

이 저장소의 검증은 코드 테스트보다 구조 검증에 가깝습니다. 변경을 제출하기 전에 아래를 확인합니다.

  • 링크가 정상적으로 열리는지, 페이지 제목이 파일 용도와 맞는지 확인
  • 새 페이지를 index.md에서 찾을 수 있는지 확인
  • ingest, 질의, lint 작업에 대해 log.md에 날짜가 포함된 항목 추가
  • raw/imports/에 넣은 보관본마다 대응하는 wiki/source-*.md가 있는지 확인
  • type: source 문서의 updated 날짜와 log.md의 마지막 관련 날짜가 일치하는지 확인
  • ingest한 source 문서에서 최소 하나 이상의 concept, entity, comparison 문서로 직접 연결되는지 확인
  • freshness 기준은 source 문서에만 적용하고, 파생 문서는 같은 변경 단위에서 함께 갱신하는 수준으로 유지
  • 새 주장이나 요약이 소스에 근거하는지, 혹은 합성 해석인지 명확히 구분

스크립트가 도입되면 해당 스크립트 옆에 테스트를 추가하고 실행 명령도 이 문서에 기록합니다. 원격 저장소를 쓴다면 .github/workflows/verify.yml이 make verify를 자동 실행하도록 유지합니다. 웹에서 문서를 공개할 때는 docs/web-publishing.md의 MkDocs/Vercel 절차를 따릅니다.

커밋과 풀 리퀘스트 가이드

이 스냅샷에는 Git 히스토리가 없으므로 간단한 규칙을 사용합니다. 커밋 메시지는 Add source ingest log format, Update index for book notes처럼 짧은 명령형으로 작성합니다.

PR에는 무엇이 바뀌었는지, 위키의 어느 영역이 영향을 받았는지, index.md와 log.md를 갱신했는지 설명해야 합니다. 스크린샷은 시각적 도구나 렌더링 결과가 중요한 경우에만 포함합니다.

에이전트 전용 지침

에이전트는 raw 소스를 다시 쓰면 안 됩니다. 역할은 위키 레이어를 합성하고, 상호 링크를 만들고, 일관성을 유지하는 것입니다. 관련 페이지와 index.md, log.md를 함께 다루는 작고 검토 가능한 수정 단위를 선호합니다.