AI 협업·문서 갱신

상태: 팀·AI 작업 안내 · 확인일: 2026-10-28

AI에게 전달하는 순서

처음에는 이 사이트의 종합 개요와 개발 현황을 전달한다.
작업할 모드 규칙과 해당 스테이지·젤리·장비를 추가한다.
현재 표시 번호 + stageId로 대상을 지정하고 기대 동작·완료 기준·변경하지 않을 판정을 말한다.
저장소에 접근 가능한 AI는 루트 AGENTS.md, PROGRESS.md, 관련 스펙·계획과 실제 코드를 읽는다. 문서의 요약이 저장소 작업 규칙을 대체하지 않는다.

예: “현재 61판 / stage-064의 보호색 곰 벨트에서 고양이 발 장비의 외관을 검토해줘. 보호색·압착 판정은 유지하고 실기기 검증 여부를 구분해줘.” 번호는 현재 전체 스테이지에서 다시 확인한다.

JavaScript 없이 읽는 경로

기본 페이지는 본문이 정적 HTML에 포함된다.
AI 문서 색인은 모든 주제의 HTML과 Markdown 경로를 안내한다.
개요 Markdown, 규칙 Markdown, 개발 현황 Markdown, 젤리 Markdown, 장비 Markdown, 스테이지 Markdown을 직접 전달할 수 있다.
사이트맵은 현재 빌드의 HTML 주소 목록이다.

llms.txt가 모든 AI의 자동 발견을 보장하지 않는다. 비공개 환경에서는 인증·봇 정책 때문에 URL 접근이 실패할 수 있으므로, AI가 저장소 DocsSite/src/content/docs/ 또는 생성된 DocsSite/public/ 원문을 읽게 한다.

문서와 코드의 역할

자료	역할	편집 방법
`src/content/docs/index.md`, `modes.md`	목적·규칙·공통 용어	근거 코드·스펙과 함께 직접 수정
`src/content/docs/status.md`	확인일 기준 완료·시제품·검증 대기	기능 통합마다 최근 기록과 코드 대조
`src/content/docs/catalog/*.md`	코드에서 만든 현재 목록	직접 고치지 말고 생성기·원본 데이터 수정
`scripts/generate.ts`	현재 목록·이미지·근거 사본·AI 출력 생성	원본 모듈을 읽는 방식 유지
`PROGRESS.md`, `docs/superpowers/specs/`	개발 이력·판정 근거	기존 저장소 방식으로 갱신, 승인 없는 의미 삭제 금지

목록은 생성할 때 현재 코드를 읽는다. 개발 현황의 완료 판단·검증 기록·수동 규칙 설명까지 자동으로 바뀌지는 않는다. 과거 문서의 번호 대신 현재 stage-order.json 순서를 사용한다.

기능 변경 후 갱신 순서

구현·검증 결과를 기존 PROGRESS.md에 기록하고 관련 근거 스펙을 갱신한다.
status.md와 영향을 받는 설명의 상태·확인일·미검증 항목을 수정한다.
DocsSite/에서 npm ci(최초 또는 의존성 변경 후), npm run check, npm run build를 실행한다.
생성표의 실제 배치 여부·고정 ID·가격과 HTML/Markdown의 핵심 정보가 일치하는지 확인한다.
시각 수정이 있으면 선택한 검수 방식에 맞춰 사용자가 외관을 확인한다. 빌드 성공을 시각 승인으로 간주하지 않는다.

기존 문서 내용의 삭제·의미 폐기·전체 교체는 구체적인 대상에 대해 사용자 확인이 필요하다. 이 작업은 현재 브랜치에서 수행하며 자동 브랜치 전환·커밋·배포를 하지 않는다.

팀원 로컬 실행

저장소의 DocsSite/start-docs.command(macOS) 또는 DocsSite/start-docs.cmd(Windows)를 더블클릭한다. 호환 Node/npm이 없으면 공식 Node 런타임을 프로젝트 안에 준비한다. 최초에는 런타임·npm 다운로드를 위한 네트워크와 디스크 공간이 필요하다. 정확한 요구 버전과 미검증 환경은 DocsSite/README.md를 확인한다.

수동 실행은 저장소 루트에서 아래 명령을 한 줄씩 실행한다.

cd DocsSite
npm ci
npm run dev

127.0.0.1에만 서버를 연다. 더블클릭 실행기는 48731이 사용 중이면 48732~48750을 확인하고 실제 URL을 안내한다. 다른 서버를 종료하지 않는다. 종료는 실행 터미널의 Ctrl+C다.

공유·배포 범위

문서 최초 작성 단계는 로컬 준비까지였고, 이후 배포 요청으로 **https://jelly-docs.steadyloop.dev**를 공개했다. 팀원은 이 URL이나 저장소 로컬 실행을 사용할 수 있다. 배포 빌드의 SITE_URL은 같은 HTTPS 원점으로 설정해 Markdown 색인과 사이트맵에 반영한다. 자동 배포는 개발 현황의 실제 검증 상태를 확인한다.

Cloudflare Workers Static Assets 배포를 검토할 수 있다. 루트 DocsSite, 빌드 npm run build, 출력 dist, 운영 브랜치 main을 기준으로 하되 게임 배포와 별개로 연결한다. 자동 생성 입력이 저장소 밖이 아니라 상위 폴더에 있으므로 DocsSite/**뿐 아니라 src/**, 루트 package.json·package-lock.json, docs/**, PROGRESS.md, AGENTS.md, capacitor.config.ts 변경도 빌드 필터에 포함해야 한다. 실제 설정은 Cloudflare 공식 안내를 확인하고 별도 배포 요청에서 확정한다.