문서 유지보수

공개 사이트와 저장소 안내는 같은 Markdown 원문을 사용합니다. 영문을 편집 기준으로 삼고 각 문서에 검토된 한국어판을 유지합니다. 영문이 불명확하면 먼저 고친 뒤 동작·제약·예시가 같은 자연스러운 한국어로 작성하세요.

내용과 표현 검토

현재 코드·설정·테스트와 문서를 대조합니다. 구현된 동작, 설정에 따른 사용 가능 여부, 테스트 범위, 실제 배포 검증을 구분하세요. 내부 구현 이름보다 독자가 할 수 있는 일을 먼저 설명하고 필요한 기술 용어는 처음 등장할 때 풀이합니다.

설명 없는 작업 번호, 과거 세션의 주장, 반복되는 부정 비교, 관련 없는 저장소 이름을 피합니다. 의존성 출처와 유용한 소스 링크는 유지하세요. 표의 설명과 탐색 문구는 번역하고 API 식별자는 보존합니다. 한국어는 영어 어순을 그대로 옮기지 않고 독립적으로 자연스럽게 읽혀야 합니다.

각 사실을 자세히 설명하는 기준 페이지를 정하고 다른 곳에서는 연결합니다. 설치 절차는 재현 가능하게 작성하고, 자리표시자와 실행 가능한 예시를 구분하며, 결과가 불확실하면 성공을 암시하지 말고 처리 방법을 설명합니다. 해시를 기록하기 전에 문서 쌍 전체를 다시 읽고 일관성을 확인하세요.

문서 등록과 호환성

레지스트리는 문서 ID, 경로, 탐색 그룹, 앵커, 검토한 파일 해시를 기록합니다. 루트 안내는 .ko.md, 다른 번역은 docs/ko/에 둡니다. 대응 문서가 있으면 같은 언어로 연결하세요.

절 제목을 바꿔도 기존 경로와 앵커는 보존합니다. 이전 앵커를 새 절 가까이에 명시적으로 두세요. 새 관리 문서에는 두 언어와 등록 항목이 필요합니다. 해시는 이후 편집을 감지할 뿐 의미 일치나 편집 검토를 증명하지 않습니다.

변경한 문서 쌍을 검토한 뒤 해당 ID를 명시하여 기록합니다.

python3 -B scripts/check_docs.py record --id agent-integration
python3 -B scripts/check_docs.py

검사 실패를 없애기 위해 모든 해시를 갱신하지 마세요. 렌더링한 페이지, 복사되는 Markdown, 언어 이동, 기존 링크가 의도한 내용과 일치하는지도 확인합니다.

빌드와 미리 보기

Node 24.21.0, npm 11.19.0, Python 3.11 이상을 사용합니다. CI는 Python 3.14를 사용합니다. Python 실행 파일 이름이 다르면 DOCS_PYTHON을 설정하세요. 사이트는 커밋된 VitePress 잠금 파일을 사용하며 문구 수정에 의존성 업데이트를 섞지 않습니다.

npm ci --prefix docs-site --ignore-scripts
npm test --prefix docs-site
npm run build --prefix docs-site
python3 -B docs-site/scripts/site.py check
python3 -B docs-site/scripts/site.py preview

미리 보기 주소는 http://127.0.0.1:43141/CodeSpace/입니다. 수정 후에는 미리 보기를 중지하고 다시 빌드한 뒤 재시작하세요. 시작할 때 읽은 manifest와 일치하는 파일만 제공하기 때문입니다. Vite 개발 서버 대신 검증된 정적 미리 보기를 사용합니다. 영문은 루트, 한국어는 /ko/이며 안내 문서는 /guide/, /ko/guide/에 있습니다. 페이지 복사는 현재 언어의 Markdown 원문을 사용합니다. 검색은 브라우저 안에서 수행합니다.

두 테마에서 데스크톱과 좁은 화면을 확인하고 긴 코드·표도 점검하세요. 탐색, 언어 전환, 검색, 복사를 실제로 사용해 봅니다. 레지스트리와 빌드 검사 통과만으로 가독성이나 정확성이 보장되지는 않습니다.

게시와 출처

PR은 리뷰용 산출물을 빌드하며 배포하지 않습니다. main push 또는 main의 수동 workflow가 검증한 디렉터리를 GitHub Pages에 게시합니다. 빌드 메타데이터에 소스 커밋과 원문 해시를 기록하지만, 산출물 업로드 성공이 실제 게시 완료의 증거는 아닙니다.

사이트 구현은 MIT, 프로젝트 문서는 Apache-2.0을 따릅니다. 사이트 출처, 의존성 고지, 라이선스 파일을 보존하세요. 게시 workflow는 배포 잠금 기록의 검토된 외부 액션을 사용합니다. 이 액션은 별도의 의존성 검토를 거쳐 변경합니다. 저장소의 Pages·환경 설정은 운영자가 관리하며 빌드가 생성하지 않습니다.