Context#
프로젝트는 초기 리서치에서 시작해 브랜드, 마케팅, 제품, 기술로 확장된다. 문서 대부분을 LLM이 만들고 갱신하며, 팀은 브라우저에서 결과를 읽어야 한다.
Decision#
raw/를 커밋 이후 불변인 source of truth로 사용한다.- LLM이
wiki/의 Markdown을 소유하고 증분 통합한다. AGENTS.md를 스키마와 작업 계약으로 사용한다.- source-id로 raw → source card → 주장/결정을 추적한다.
- Markdown wiki를 정적 HTML로 빌드해 GitHub Pages에 배포한다.
raw/는 Pages artifact에 포함하지 않는다.
이 결정은 Karpathy가 제안한 raw/wiki/schema 구조와 ingest/query/lint 운영을 따른다. [1] GitHub Pages는 공식 custom workflow의 build artifact 배포 방식을 사용한다. [2]
Why Markdown canonical, HTML delivery#
Markdown은 LLM 편집 비용이 낮고 diff와 cross-link가 명확하다. HTML을 직접 canonical 문서로 두면 콘텐츠와 표현 마크업이 섞여 wiki 갱신 비용과 오류 면적이 커진다. 팀의 요구인 HTML 읽기 경험은 빌드 결과가 충족한다.
Consequences#
- 사람이
tools/wiki-publisher/dist/나 개별 HTML을 직접 관리하지 않는다. - 위키 발행용 Node.js 도구 체인은 모두
tools/wiki-publisher/에 격리한다. - 제품 랜딩페이지는 향후
apps/landing/에 두어 위키 발행 도구와 분리한다. - 좋은 질의 결과와 결정이 채팅에서 사라지지 않고 wiki에 축적된다.
- raw가 별도로 남아 LLM 요약을 재검증하거나 wiki를 재구축할 수 있다.
- Pages 공개 범위와 저장소 접근권한은 민감 리서치 수집 전에 확인해야 한다.
Revisit when#
- 위키가 수백 페이지로 커져 현재 파일 검색이 충분하지 않을 때
- 팀별 검토/승인 워크플로가 필요할 때
- 민감 자료와 공개 지식의 저장소를 물리적으로 분리해야 할 때