kordoc: Instructions file for Codex

kordoc 작업 지침

kordoc — 한국 공문서(HWP 3.x·5.x, HWPX, HWPML, PDF, XLS·XLSX, DOCX, PPTX, 이미지)를 Markdown·IR 로 바꾸고 비교·생성하는 파서 라이브러리. npm 패키지로 배포하고 라이브러리 API·CLI(kordoc)·MCP 서버(kordoc-mcp, 도구 22개)를 낸다.

이 파일이 에이전트 공통 지침의 정본이다. Codex 는 이 파일을 바로 읽고, Claude Code 는 CLAUDE.md 의 @AGENTS.md 로 읽는다. 상세 참고: docs/architecture.md(모듈 구조·설계 결정·구현 주의 상세), docs/corpus.md(벤치 코퍼스 이력), docs/benchmarks.md(채점 기준·옵션별 수치), docs/gongmunseo-engine-spec.md(공문서 생성 엔진).

0. 최우선 규칙: 독자 구현

다른 모든 지침보다 앞섬 (2026-10-25 확정).

1. 경쟁 제품(다른 한글 문서 편집기·오피스 앱) 저장소의 코드·패치·시험·문구·빌드 결과를 옮기지 않음. 라이선스가 허락해도 금지.
2. 경쟁 제품은 기능 비교(무엇이 있나)까지만 봄. 구현을 보고 따라 짜지 않음. 구현 근거는 공개 명세(한컴 공식 도움말·HWP 공개 문서), rhwp 원본(MIT), kordoc 뿐.
3. 엔진은 kordoc + npm rhwp 원본. rhwp 결함은 rhwp 에 PR 로 고침. 남의 패치 묶음을 들고 있지 않음.
4. 예전에 옮겨 온 코드(NOTICE 에 적힌 것)는 우리 코드로 차례로 다시 짜고, 다 바꾸면 NOTICE 에서 뺌.
5. 커밋 메시지·README·화면 문구에 경쟁 제품 이름 금지. 우리 프로젝트 이야기만 짧게.

작업 규칙

• 사용자가 개선 완료와 반영을 요청한 작업은 검증 후 main에 반영하고 원격에 푸시한다. 이 저장소에서는 별도 PR이 필수 경로가 아니다. 병렬 작업과 충돌할 수 있으면 독립 worktree에서 준비한 뒤 최신 main을 확인하고 반영한다.
• 배포까지 요청되었거나 사용자가 이 작업에 적용한 배포 관례를 명시했다면, 검증된 main에서 버전·메타·변경 내역을 맞춘 뒤 npm 게시와 GitHub 릴리스를 완료한다. 게이트 실패나 불명확한 게시 상태가 있으면 원인을 해결하고 이중 게시를 피한다.
• 다른 작업 공간의 미커밋 파일과 코퍼스 심링크는 건드리거나 커밋하지 않는다. 관련 없는 PR의 변경은 섞지 않는다.
• PDF 품질 작업에서는 정답·평가기·제외 모수를 바꾸어 점수를 높이지 않는다. 외부 ODL 200문서, 한국 공문서 PDF 표·글, HWPX/HWP5 및 자원 사용을 따로 검증한다.
• 상위 공통 지침의 Git 정책과 다른 부분은 사용자가 이 저장소에 대해 2026-09-25에 명시한 main 반영·푸시·배포 관례를 따른다. 이후 사용자가 작업별로 범위를 제한하면 그 지시를 우선한다.
• 채점기·정규화를 바꿔야 하면(새 출력 표지를 걷는 등) CHANGELOG 에 "채점 기준 변경"으로 적는다.

명령

npm run build          # tsup — ESM+CJS 라이브러리 + CLI·MCP 바이너리 → dist/
npm run dev            # watch 모드
npm test               # node --import tsx --test tests/*.test.ts
npm run typecheck      # tsc --noEmit
npm run bench:gate     # 코퍼스 회귀 게이트 체인(pages·score·roundtrip·pdf-table·pdf-text·formats·fuzz·reflow·redact·ocr·hwp2hwpx)
npm run bench:visual   # 선택 진단: 한컴 실렌더 비교 (macOS GUI 전용 — bench/visual/, 순수 로직은 hash-lib.mjs)
npm run sync-meta      # 공문서 엔진 스펙·구성 기준 정본(docs/) → 스킬 사본(.claude/skills/gongmunseo/references/) 동기화
node bench/predict-layout.mjs 문서.hwpx --loose   # 생성 공문서의 한글 조판 예측(실글꼴 폭표, 한글 2024 PDF 154줄 재현) — 한컴 없이 벌어진 줄·고아 줄·압축 확인