[chucoding]

Purpose

코드만 읽어서는 알기 어려운 설계 의도와 제약이 PR 본문과 코드 주석에 흩어져 있어, 에이전트가 참조할 정본이 저장소 안에 없었다. Notion WIKI 설계를 따라 카파시 LLM Wiki 패턴을 OKF v0.2 번들로 구축한다. (#94)

Description

위키 위치: 이 저장소 wiki/

• 코드와 문서를 한 PR에서 함께 고쳐 어긋남을 막고, 에이전트가 파일을 직접 읽어 MCP가 필요 없다.
• 저장소가 public이라 비밀 값, 비용과 매출 수치, 개인정보, 운영 계정 정보는 쓰지 않는다. 근거와 다시 검토할 시점은 wiki/decisions/wiki-location.md에 남겼다.

위키 내용

• 개념 문서 7건: 시스템 구성, Firestore 데이터 경계, 공개 AI 함수 호출 경계, 카드 생성 경로, 서버 사전 생성, 덱 문서 크기 예산, 위치 결정 기록
• 모든 문서는 실제 코드 파일과 관련 PR을 sources로 연결했다. 문서에 적은 상수 값은 코드와 대조했다.
• 머리말은 OKF 필수인 type 외에 title, description, status, sources, generated, stale_after까지 필수로 둔다. 시각 값은 OKF PR #6에 맞춰 UTC 오프셋을 붙인 datetime으로 쓴다.

에이전트 규칙

• AGENTS.md가 정본이고 CLAUDE.md는 @AGENTS.md 한 줄이다.
• AGENTS.md에는 항상 지킬 원칙과 이 저장소 전용 값만 둔다. 위키 작성 절차(frontmatter 형식, Ingest, Query, Lint)는 다른 프로젝트에서도 쓰도록 개인 스킬 chucoding:okf-wiki로 분리했다.

정적 검사 (pnpm wiki:lint, CI Wiki Lint)

• 자체 스크립트 scripts/wiki-lint.mjs. 의존성은 yaml 하나이고 테스트 11건이 있다.
• 검사 항목: 필수 키, status 값, 행위자와 시각 형식, 사람 확인 없는 stable, sources 경로 존재, 깨진 링크, index.md 등록 누락, log.md 형식, stale_after 만료
• CI는 wiki/**, 검사 스크립트, package.json, 워크플로 파일이 바뀐 PR과 main 푸시에서만 실행한다.

검토 후 넣지 않은 것

• 출처 변경 자동 감지: 파일 단위 판정이라 오탐이 잦다. 확인 없이 확인 기록만 추가하는 의례가 될 수 있어, 코드를 고치는 PR에서 위키도 함께 고치는 규칙에 맡겼다.
• 주기 실행(schedule): 혼자 개발하는 단계에서는 과하다고 보고 뺐다. 다른 기여자의 PR이 생기면 다시 검토한다.
• 커뮤니티 OKF 린터: okf-schema, okflint, okf-mcp, superops-team/okf를 이 위키에 직접 돌려 비교했다. 모두 datetime stale_after 만료를 놓치거나 형식 오류로 본다. 쓸 만한 okf-schema도 도구 전용 설정(_schema/), 한 줄 목록 변환, type 변경이 필요했고 index.md 등록과 log.md 순서를 보지 않아 자체 스크립트를 유지했다.
• OpenSpec: 위키와 다른 계층이고 개발 흐름 자체를 바꾸는 일이라 #95로 분리했다.

How to test

• pnpm wiki:test: 11건 통과
• pnpm wiki:lint: 오류 0건, 경고 0건
• 검사 규칙 확인: 출처 파일, 시각 형식, 필수 키를 일부러 깨뜨렸을 때 실패하는 것을 확인함
• GitHub Actions Wiki Lint: 이 PR에서 처음 실행됨
• vitest와 E2E: 미실행. 저장소에 vitest 환경이 없고 화면 변경이 없음

Review Requirement

• 개념 문서 7건은 모두 status: draft이고 사람 확인 기록이 없다. 내용을 확인한 문서는 verified에 human:chucoding을 추가하고 stable로 올려야 한다.
• AGENTS.md가 가리키는 chucoding:okf-wiki 스킬은 skills 저장소에서 별도로 만드는 중이다. 그 PR이 머지되기 전까지는 아직 없는 스킬을 가리킨다.

Additional Info

• Notion 설계: https://app.notion.com/p/chucoding/WIKI-3a9fd64d44a080bd8e71e0bebb96e55f
• 후속 이슈: OpenSpec 도입 검토 #95 OpenSpec 도입 검토
• 커뮤니티 린터에 올린 datetime stale_after 이슈: stale_after (and other timestamps) in ISO 8601 datetime form are rejected by S204 and silently skipped by S209 mattdav/okflint#5, stale_after as an ISO 8601 datetime (OKF v0.2 after spec PR #6) is never reported as stale (W11) gsemet/okf-schema#37
• OKF 시각 표기 근거: Make every timestamp an ISO 8601 datetime with an explicit offset GoogleCloudPlatform/open-knowledge-format#6

🤖 Generated with Claude Code