# wax 사용 매뉴얼

wax는 기능 하나를 **기획 → 설계 → 구현 → 검토 → 보고**로 나누어 진행하고, 문서와 완료 근거를 프로젝트에 남깁니다.

## 1. 어떤 프로젝트를 사용하나요?

| 프로젝트 | 용도 | 필요 조건 |
| --- | --- | --- |
| `wax-plugin` | AI 코딩 도구 안에서 코드 수정·검증 수행 | Node.js 22 이상, 로그인된 Codex, Claude Code, Gemini CLI 또는 Antigravity CLI |
| `wax-service` | 브라우저에서 작업·문서 관리, AI 초안 생성 | Node.js 22 이상. AI 생성에만 별도 API 키 필요 |
| `wax-site` | 소개·설치 안내 확인 | 로컬 미리보기에 Node.js 22 이상 |

플러그인은 [wax 사이트](https://wax.me2shop.com/#download)에서 로그인 없이 ZIP으로 내려받을 수 있습니다. ZIP에는 플러그인 소스·테스트·매뉴얼이 포함되며 웹 서비스는 포함되지 않습니다. 웹 서비스는 현재 내부 개발 버전입니다. wax 코드에는 MIT 라이선스가 적용되며 AI 호스트와 API의 사용 요금·한도는 별도입니다.

## 2. 코드 내려받기

ZIP을 **모두 압축 풀기**로 해제한 뒤 내부에 `package.json`과 `bin/wax.mjs`가 있는 `wax-plugin` 폴더를 찾습니다. `.claude-plugin` 숨김 폴더도 포함되어 있어야 합니다. 플러그인은 `npm install` 없이 실행됩니다.

Windows·WSL 예제와 업데이트 방법은 ZIP 안의 `INSTALL.md`를 참고하세요. 이 매뉴얼에서 `/mnt/d/project/wax/wax-plugin`은 예시 경로입니다. 반드시 압축을 푼 실제 절대 경로로 바꾸세요.

아래 예제에서 `/path/to/my-app`은 **실제로 코딩할 프로젝트 디렉터리**로 바꾸세요. 해당 디렉터리는 먼저 존재해야 합니다. 플러그인 소스 디렉터리와 작업할 프로젝트를 구분하세요.

## 3. Claude Code에서 첫 작업 시작

작업할 프로젝트에서 wax 플러그인을 로드합니다. 이 방식은 해당 Claude 세션에 적용되므로 새 세션을 열 때 같은 옵션을 사용하세요.

```sh
cd /path/to/my-app
claude --plugin-dir "/mnt/d/project/wax/wax-plugin"
```

다른 컴퓨터에서는 `--plugin-dir` 뒤의 경로도 실제 위치로 바꾸세요. npm 설치 없이 동작합니다.

Claude 대화창에서 기능을 요청합니다.

```text
/wax:plan email-login 이메일과 비밀번호로 로그인하는 기능을 만들어줘
```

wax가 기존 코드를 확인하고 요구사항·범위·수용 기준을 정리합니다. 결정이 필요한 질문에 답한 뒤 결과를 확인하세요. 한 명령은 그 단계의 작업을 수행하며, 모든 후속 단계를 한꺼번에 실행하지 않습니다.

## 4. 단계를 차례로 진행

| 명령 | 하는 일 |
| --- | --- |
| `/wax:plan email-login …` | 새 기능의 문제·범위·수용 기준 정리 |
| `/wax:design email-login` | 구조·데이터·수정 파일·검증 방법 설계 |
| `/wax:implement email-login` | 호스트의 도구로 실제 코드 수정 및 관련 검사 실행 |
| `/wax:review email-login` | 설계와 실제 결과 비교, 테스트 근거와 미검증 항목 기록 |
| `/wax:report email-login` | 결과·검증·사용법·남은 과제 정리 |
| `/wax:status email-login` | 현재 단계와 완료 근거 확인 |
| `/wax:iterate email-login 만료 토큰 처리 개선` | 이전 주기를 보관하고 구현 단계로 돌아가기 |

예를 들어 첫 기획을 마친 후 다음 명령을 한 번씩 실행합니다.

```text
/wax:design email-login
/wax:implement email-login
/wax:review email-login
/wax:report email-login
```

현재 단계의 문서와 완료 근거가 있어야 다음 단계로 넘어갑니다. 검토는 확인된 통과 판정이 추가로 필요합니다. 해결되지 않은 문제나 미검증 기준이 남으면 검토를 완료하지 않고 그 이유를 알려줍니다. 실제로 실행하지 않은 테스트는 통과했다고 기록하면 안 됩니다.

검토에서 문제가 발견됐다면 다음과 같이 개선합니다.

```text
/wax:iterate email-login 만료된 인증 토큰을 거부하도록 개선
/wax:implement email-login
/wax:review email-login
/wax:report email-login
```

기능 ID는 영문 소문자·숫자로 시작하며 소문자·숫자·하이픈만 포함하는 1~64자입니다. `email-login`, `dashboard`, `payment-v2`처럼 정하세요.

## 5. Gemini CLI에서 사용

처음 한 번 확장을 연결합니다.

```sh
gemini extensions link "/mnt/d/project/wax/wax-plugin"
cd /path/to/my-app
gemini
```

새 Gemini 세션에서 Claude와 같은 `/wax:plan`, `/wax:design` 등의 명령을 사용합니다. 확장 연결이나 명령 파일 변경 후에는 세션을 다시 시작하세요. 이 프로젝트에서 Gemini TOML 문법은 검사했지만 실제 Gemini 호스트 실행은 아직 검증하지 않았습니다.

설치 버전은 플러그인 폴더에서 `node bin/wax.mjs --version`으로 확인합니다.

## 5-1. Codex에서 사용

압축을 푼 원본 플러그인과 대상 프로젝트를 연결합니다. 원본은 계속 같은 위치에 두세요.

```sh
node "/mnt/d/project/wax/wax-plugin/scripts/install-codex.mjs" --project "/path/to/my-app"
node "/mnt/d/project/wax/wax-plugin/scripts/install-codex.mjs" --project "/path/to/my-app" --check
cd /path/to/my-app
codex
```

Codex의 `/skills`에서 7개 스킬을 확인하고 대화창에서 사용합니다. 다음 예시는 터미널 명령이 아닙니다.

```text
$wax:plan email-login 이메일 로그인 구현
$wax:design email-login
$wax:implement email-login
$wax:review email-login
$wax:report email-login
$wax:status email-login
$wax:iterate email-login 만료 토큰 처리 개선
```

설치기는 프로젝트의 `.agents/skills/wax-*`에 원본 스킬을 연결합니다. 기존 다른 스킬이나 Codex 설정을 덮어쓰지 않으며 같은 설치를 반복해도 됩니다. Windows는 디렉터리 junction, Linux·WSL은 심볼릭 링크를 사용합니다. 원본 경로가 바뀌면 설치 확인이 실패하므로 기존 링크를 확인한 뒤 다시 연결하세요. 새 스킬이 보이지 않으면 Codex를 재시작합니다.

현재 단계의 문서·완료 근거와 `.wax/features` 기록은 다른 호스트와 공유합니다. Codex 자체의 로그인·도구 권한을 사용하며 웹 서비스의 AI API 제공자를 자동 변경하지 않습니다.

## 5-2. Antigravity CLI에서 사용

Antigravity CLI(`agy`)는 프로젝트의 `.agents/skills`에서 스킬을 읽으므로 5-1절의 설치기를 그대로 사용합니다. Codex용으로 이미 연결했다면 추가 설치가 필요 없습니다.

```sh
node "/mnt/d/project/wax/wax-plugin/scripts/install-codex.mjs" --project "/path/to/my-app" --check
cd /path/to/my-app
agy
```

새 세션의 `/skills`에서 7개 스킬을 확인합니다. Antigravity CLI는 스킬을 슬래시 명령으로 바꾸므로 `/plan email-login 이메일 로그인 구현`, `/design email-login`처럼 스킬 이름으로 호출합니다. 실제 표시 이름은 `/skills` 목록을 따르며, 이름이 겹치면 "wax plan 단계를 실행해줘"처럼 요청할 수 있습니다.

`agy plugin install`이나 `agy plugin import gemini`는 파일을 다른 위치로 복사·변환하므로 스킬이 함께 제공되는 CLI를 찾지 못할 수 있습니다. 프로젝트 연결 방식을 사용하세요. 실제 Antigravity CLI 세션 실행은 아직 검증하지 않았습니다.

## 6. 웹 서비스 실행

이 절은 별도로 웹 서비스 개발본을 받은 사용자를 위한 안내입니다. 공개 플러그인 ZIP만으로는 웹 서비스를 실행할 수 없습니다.

```sh
cd /mnt/d/project/wax/wax-service
npm ci --offline
cp .env.example .env
```

이미 `.env`를 설정했다면 복사 명령을 다시 실행하지 마세요. `.env`의 프로젝트 경로를 **플러그인으로 작업하는 디렉터리와 동일하게** 지정합니다.

```dotenv
WAX_PROJECT=/path/to/my-app
PORT=4310
```

서버를 시작합니다.

```sh
npm start
```

브라우저에서 `http://127.0.0.1:4310`을 엽니다.

1. **새 작업**에서 이름, ID, 설명을 입력합니다. 기존 플러그인 작업이 있으면 보드에서 그 작업을 엽니다.
2. 현재 단계의 문서를 작성하고 **문서 저장**을 누르거나 `Ctrl+S` / `⌘S`로 저장합니다. 문서 아래에 저장 상태와 글자 수가 표시됩니다. 문서를 저장해도 작성 중인 완료 근거는 유지됩니다.
3. **프롬프트 복사**로 단계별 지시문을 코딩 도구에서 사용할 수 있습니다.
4. 결과를 확인한 뒤 **완료 근거**를 입력하고 **이 단계 완료**를 누릅니다.
5. 검토 단계에서는 수용 기준 검증 및 차단 문제 해결 확인이 필요합니다.
6. 수정이 필요하면 개선 사유를 입력하고 **구현 단계로 돌아가기**를 누릅니다.
7. **문서 다운로드**는 현재 보고 있는 문서를 Markdown으로 내려받습니다. 저장 전 편집 내용도 포함합니다. **저장 기록 JSON**은 서버에 저장된 작업 기록을 내려받습니다.

보드의 **작업 검색**에서 제목·ID·설명을 검색하고, 상태 필터와 최근 수정순·최근 생성순·이름순 정렬을 함께 사용할 수 있습니다. 검색 결과가 없으면 **검색·필터 초기화**로 전체 작업을 다시 봅니다.

API 키 없이도 위 작업 관리 기능은 동작합니다. 플러그인에서 바꾼 기록은 **모든 작업** 또는 페이지 새로고침으로 불러옵니다. 작업 창의 **최신 기록 불러오기**로 다른 세션의 변경을 확인하세요. 문서 초안은 복구 패널에 남깁니다.

### 6.1 문서 초안과 AI 결과 복구

**이 프로젝트의 초안을 이 브라우저에 보관**을 켜면 저장 전 문서가 새로고침 후에도 복구 패널에 남습니다. 기본값은 해제이며, 해제한 상태에서는 현재 탭에서만 유지합니다. 같은 사이트 주소·포트와 프로젝트에서 사용하세요. 공유 컴퓨터에서는 문서 내용이 브라우저에 남는 점을 고려해 선택하세요. 보관을 해제하면 이 프로젝트의 브라우저 보관본을 삭제합니다.

복구 패널에서 초안을 선택하고 저장 문서와 비교합니다. **편집기로 가져오기**는 최신 기록을 다시 읽으며, 변경을 발견하면 먼저 최신 문서를 표시합니다. 대조한 후 다시 가져오기를 누르고 **문서 저장**으로 확정하세요. 단계·개선 주기가 다르거나 보관된 작업은 다운로드만 가능합니다. 가져오기만으로 서버 문서를 덮어쓰지 않습니다.

AI 생성 도중 다른 도구가 저장하면 생성된 초안을 복구 패널에 표시합니다. 초안 다운로드·재편집이 가능하며, 기존 문서는 유지합니다. 0.3.0부터 탭을 닫은 요청도 서버의 AI 작업·사용량 목록에서 다시 확인할 수 있습니다.

브라우저 보관이 차단되거나 용량이 부족하면 안내를 표시하고 현재 탭에 초안을 유지합니다. 닫기 전에 다운로드하세요. 0.3.0부터 완료 근거·AI 추가 문맥·작업 이름·설명 등도 입력 폼 초안으로 복구합니다.

### 6.2 작업 수정·보관과 이전 주기 비교

- **작업 이름·설명 수정**에서 정보를 바꾸고 저장합니다. 문서·완료 근거는 유지하며 변경 전후를 이력에 기록합니다.
- **작업 보관**은 작업을 기본 보드에서 숨깁니다. **보관함**에서 열어 **작업 복원**으로 되돌립니다. 보관 중에는 문서 수정·단계 완료·AI 생성을 차단합니다.
- **개선 주기 문서 비교**에서 단계와 두 주기를 선택하면 저장된 문서·근거·개선 사유를 나란히 봅니다. 이전 주기 문서는 Markdown으로 내려받을 수 있습니다.
- CLI도 `edit <id> --title <제목> --description <설명>`, `archive <id>`, `restore <id>`를 지원합니다. 직전에 읽은 `--revision` 값을 함께 전달하세요.

이 기능을 함께 사용하는 플러그인·서비스는 모두 0.3.0 이상으로 업데이트하세요. 이전 버전은 새 수정·보관 이력을 지원하지 않습니다.

### 6.3 AI 작업 재접속과 취소

**AI 초안 생성**은 작업 번호를 만들고 서버에서 계속 실행합니다. 상세 창을 닫거나 새로고침한 뒤 보드의 **AI 작업·사용량**에서 상태를 확인하세요. **결과 열기**는 서버에 보관된 결과를 복구 패널로 가져옵니다. 생성 중 다른 도구가 저장했다면 원본을 덮어쓰지 않고 결과를 비교하도록 남깁니다.

상태는 생성 중·저장 중·저장 완료·결과 복구 가능·실패·취소됨·서버 중단으로 구분합니다. 서버가 종료된 작업은 자동 재호출하지 않습니다. 이미 저장된 결과는 다시 열 수 있지만 응답을 받기 전 중단된 외부 요청 자체를 이어 실행하지는 않습니다. **생성 취소**는 서버 요청을 중단하며 제공자가 이미 처리한 사용량은 청구될 수 있습니다.

AI 작업 정보는 `.wax/service/jobs/`, 결과 문서는 `.wax/service/results/`에 저장합니다. 브라우저 초안 보관 여부와 별도로 서버에 남으며 API 키는 저장하지 않습니다. 현재 화면에는 최근 50개 요청을 표시합니다.

### 6.4 프로젝트 작업 기록 백업·복원

**작업 기록 백업**으로 작업 문서·이력·첨부 Git/테스트 근거를 하나의 JSON으로 내려받습니다. 소스 코드, API 키, 서버 AI 작업 내역과 브라우저 초안은 포함하지 않습니다.

**백업 복원**에서 파일을 선택하고 **손상·충돌 미리보기**를 누릅니다. 체크섬·기록 형식·ID 충돌을 확인한 뒤 새 작업만 복원합니다. 기존 작업을 덮어쓰지 않으며 기존 ID나 손상된 파일을 보존합니다. `restored-` 같은 접두사를 넣으면 별도 사본으로 복원합니다. 웹은 20MB 이하, 백업은 1,000개 이하 작업을 지원합니다.

복원 도중 실패하면 복원·건너뜀·남은 작업 수를 표시합니다. 원인을 해결하고 다시 미리보기한 뒤 재시도하세요. 이미 성공한 작업은 보존합니다. CLI도 지원합니다.

```sh
node /path/to/wax-plugin/bin/wax.mjs backup --project /path/to/project > wax-backup.json
node /path/to/wax-plugin/bin/wax.mjs import --project /path/to/project --file wax-backup.json --prefix restored-
# 미리보기에서 반환한 fingerprint 값을 그대로 사용해 확정
node /path/to/wax-plugin/bin/wax.mjs import --project /path/to/project --file wax-backup.json --prefix restored- --apply <fingerprint>
```

### 6.5 Git·테스트 검증 근거 연결

작업 상세의 **Git·테스트 검증 근거**에서 커밋 또는 브랜치 이름을 입력하고 실제 커밋과 변경 파일을 연결합니다. 커밋을 새로 만들거나 저장소 내용을 수정하지 않습니다.

테스트는 대상 프로젝트의 터미널에서 직접 실행합니다. `--` 뒤는 실행 파일과 인수입니다. 셸 문법을 자동 해석하지 않습니다. 다음 예제의 ID·경로·revision은 실제 값으로 바꾸세요.

```sh
node /path/to/wax-plugin/bin/wax.mjs evidence my-feature --commit HEAD --revision 3
node /path/to/wax-plugin/bin/wax.mjs test my-feature --revision 4 -- npm test
```

기본 제한은 120초이며 `--timeout`에 100~300000ms를 지정할 수 있습니다. 실제 종료 코드·출력 최대 20,000자·실행 시점 커밋과 작업 트리 변경 여부를 기록합니다. 출력에 민감 정보가 있는 테스트는 실행 전에 확인하세요. 웹에서 임의 테스트 명령을 실행하지 않습니다.

실패하거나 중단된 테스트도 기록하지만 단계 완료의 통과 근거로 선택할 수 없습니다. 웹에서 현재 단계·주기의 커밋 또는 통과한 테스트를 선택하고 완료하거나 CLI의 `complete ... --proofs <근거 ID,근거 ID>`를 사용합니다. 사람이 작성하는 완료 근거와 검토 판정은 계속 필요합니다.

테스트 중 다른 도구가 작업을 바꾸면 `recorded: false`와 결과 JSON을 반환합니다. 실행 결과를 보관하고 최신 상태를 확인하세요. 테스트 출력 원문을 AI 프롬프트에 자동으로 추가하지 않습니다.

### 6.6 입력 폼 복구와 선택 병합

초안 복구는 문서뿐 아니라 작업 이름·설명, 완료 근거, AI 추가 문맥, 개선 사유, 검토 선택, Git 참조와 근거 선택을 포함합니다. 새 작업 창도 입력을 보관하며 **저장 전 입력 복구**로 가져옵니다. 브라우저 보관은 기본 해제이며 프로젝트별로 선택합니다. 파일 선택과 API 키는 복구하지 않습니다.

복구 패널에서 **입력 폼**을 선택해 가져올 수 있습니다. 기록 버전이 바뀌었다면 검토 통과 체크는 해제하고 다시 확인합니다. 가져오기만으로 작업을 생성하거나 완료하지 않습니다.

문서 초안의 **저장 문서와 달라진 줄 선택**을 펼치면 추가·삭제된 줄을 보여 줍니다. 원하는 변경을 체크하고 **선택한 변경만 가져오기**를 누르면 편집기에 반영합니다. 최신 저장 기록이 바뀌었다면 먼저 다시 비교합니다. 큰 문서는 변경을 묶어서 보여 줄 수 있으며 최종 반영은 **문서 저장**으로 확정합니다.

### 6.7 여러 프로젝트와 AI 사용량 설정

서버 `.env`의 `WAX_PROJECTS`에 기존 프로젝트 경로 배열을 등록한 뒤 서버를 시작합니다. 이후 화면의 프로젝트 선택으로 전환하며 서버를 재시작할 필요가 없습니다. 등록되지 않은 경로는 웹 요청으로 열 수 없습니다.

```dotenv
WAX_PROJECTS=[{"path":"/path/to/app-one","name":"앱 1"},{"path":"/path/to/app-two","name":"앱 2"}]
WAX_AI_DAILY_LIMIT=100
WAX_AI_MAX_OUTPUT_TOKENS=4096
```

Windows 경로를 JSON에 쓰면 역슬래시를 이중으로 표기하거나 `C:/Projects/app`처럼 슬래시를 사용하세요. `WAX_PROJECTS`를 생략하면 기존 `WAX_PROJECT` 한 개를 사용합니다.

**프로젝트 AI 설정**에서 제공자·모델 ID·일일 요청 한도·최대 출력 토큰을 저장합니다. 설정은 해당 프로젝트의 `.wax/service/settings.json`에 저장하며 API 키는 서버의 제공자별 환경 변수를 공유합니다. 키 변경과 프로젝트 등록 목록 변경에는 서버 재시작이 필요합니다.

일일 한도는 UTC 날짜별 요청 횟수이며 실패·취소도 포함합니다. 0은 생성 중지입니다. 토큰 합계는 제공자가 응답한 값으로 계산하고 미확인 요청은 따로 표시합니다. 금액 예산이나 청구서가 아니므로 실제 청구는 제공자 사용 내역에서 확인하세요.

## 7. 웹의 AI 초안 생성 설정

**비용:** Claude API 호출은 Claude Pro·Max 등의 구독료에 포함되지 않습니다. 키를 설정하는 것만으로 호출하지 않으며 **AI 초안 생성** 버튼을 누르면 설정한 모델로 요청합니다. Gemini API는 모델별 무료·유료 구간이 있습니다. wax에는 금액 기준 자동 차단 기능이 없으므로 제공자의 사용 한도를 확인하세요. [Claude 공식 안내](https://support.claude.com/en/articles/9876003-i-have-a-paid-claude-subscription-pro-max-team-or-enterprise-plans-why-do-i-have-to-pay-separately-to-use-the-claude-api-and-console), [Gemini 공식 요금표](https://ai.google.dev/gemini-api/docs/pricing).

`.env`에서 하나의 제공자를 선택하고 실제 키와 모델 ID를 입력합니다. 아래 대괄호 부분을 실제 값으로 바꾸세요. 키를 Git에 올리거나 채팅에 붙여 넣지 마세요.

Claude API를 사용하는 경우:

```dotenv
WAX_AI_PROVIDER=anthropic
WAX_AI_MODEL=<해당 계정에서 사용 가능한 모델 ID>
ANTHROPIC_API_KEY=<본인 API 키>
```

Gemini API를 사용하는 경우:

```dotenv
WAX_AI_PROVIDER=gemini
WAX_AI_MODEL=<해당 계정에서 사용 가능한 모델 ID>
GEMINI_API_KEY=<본인 API 키>
```

OpenAI Responses API를 사용하는 경우:

```dotenv
WAX_AI_PROVIDER=openai
WAX_AI_MODEL=<해당 계정에서 Responses API로 사용 가능한 모델 ID>
OPENAI_API_KEY=<본인 API 키>
```

키는 서버에서만 사용하며, API 사용 요금과 한도는 선택한 모델·계정을 따릅니다. 구현은 [공식 OpenAI Responses API 규격](https://developers.openai.com/api/reference/cli/resources/responses/methods/create)을 따르고 `store: false`로 요청합니다. 잘린 응답과 거절을 완료된 문서로 저장하지 않습니다. Codex 전용 스킬과 웹 API 연결은 별도 기능입니다.

서버를 `Ctrl+C`로 종료하고 `npm start`로 다시 시작합니다. 작업을 열어 **AI와 함께 초안 작성**을 펼치고, 필요하면 코드나 조건을 추가 문맥에 붙여 넣은 뒤 **AI 초안 생성**을 누릅니다.

작업 설명, 저장된 단계 문서, 추가 문맥이 선택한 AI 제공자에게 전송됩니다. 웹은 파일을 자동으로 읽거나 실행하지 않으며 코드 초안을 실제 프로젝트에 적용하지 않습니다. 실제 편집과 테스트는 코딩 플러그인에서 진행하세요. 생성 결과를 확인하고 완료 근거를 입력해야 다음 단계로 이동합니다.

키와 모델을 설정하면 화면에는 **연결 준비됨**이 표시됩니다. 이는 설정값이 있다는 뜻이며, 키의 유효성은 실제 요청 시 확인됩니다. 실제 API를 이용한 생성 품질·요금·한도는 사용자 환경에서 확인해야 합니다.

## 7-1. 팀 대시보드: AI 세션 협업과 일일 업무보고

여러 코딩 도구 세션(Claude Code·Codex·Gemini CLI·Antigravity CLI)이 같은 프로젝트에서 일할 때, 각 세션의 AI가 **팀원**으로 참여합니다. 대화·업무 배정·일일 보고는 프로젝트의 `.wax/chat/`에 저장되고, 로컬 대시보드에서 실시간으로 확인합니다. 대시보드는 기록을 보여 줄 뿐 AI를 호출하지 않습니다. 가상 사무실의 안내 NPC(진행 소식을 전하는 제이크, 도움말·사무실을 안내하는 써니)도 외부에 접속하지 않고 프로젝트 기록과 현재 시각만으로 말합니다. NPC 안내와 캐릭터 잡담은 화면 연출이라 기록되지 않습니다. 자세한 내용은 대시보드의 **도움말**(`/help`)을 보세요.

### 대시보드 열기

```sh
node "/path/to/wax-plugin/bin/wax.mjs" --project "/path/to/my-app" dashboard
```

`http://127.0.0.1:4330/`을 엽니다(`--port`나 `WAX_DASHBOARD_PORT`로 변경). AI 세션에서 `/wax:dashboard`(Codex `$wax:dashboard`, Antigravity `/dashboard`)를 실행해도 됩니다. 이미 켜져 있으면 주소만 알려 주고, 꺼져 있으면 세션이 백그라운드로 실행하거나 따로 실행할 명령을 안내합니다. `dashboard --status`로 실행 여부만 확인할 수 있습니다. 화면 사용법은 대시보드 상단의 **도움말**(`/help`)에 정리되어 있습니다. 서버는 이 컴퓨터(127.0.0.1)에서만 열립니다. 웹에서 쓰는 사람 이름은 `WAX_CHAT_USER`로 정합니다(기본 "사람").

| 화면 | 내용 |
| --- | --- |
| `/` 대시보드 | 오늘의 숫자, 가상 사무실 패널, 타임라인(단계·근거·대화·업무·보고), 팀 상태와 "지금 하는 일", 업무 배정, 작업 진행 단계, 미해결 질문, 일일 업무보고 |
| `/chat` 채널 | 작업별 채널과 전체 채널(general)의 대화. 사람도 글을 쓸 수 있습니다 |
| `/office` 가상 사무실 | 옆에서 본 건물로, 아래에서 위로 1F 회의실·2F 개발실·3F 연구소·4F 사장실·RF 옥상 정원이 wax 작업 순서(논의 → 구현 → 검토 → 보고)를 따라 쌓여 있습니다. 같은 작업을 함께 논의 중이면 회의실, 검토 중이면 연구소, PM은 사장실, PM에게 보고하는 사람은 사장실 책상 앞, 쉬는 세션은 옥상 정원에서 담소를 나누고, 나머지는 개발실에서 일합니다. 방은 작업 단계가 아니라 세션의 지금 상태로 정해집니다. 대시보드 패널에도 같은 화면이 들어갑니다 |

날짜를 바꾸면 그날의 기록을 봅니다.

### 세션끼리 대화하기

각 세션은 wax 단계 명령을 실행할 때 자동으로 참여합니다. 단계를 시작하면 상태를 "작업 중"으로 바꾸고 그 작업 채널의 최근 메시지를 읽습니다. 단계를 마치면 맡은 업무의 상태(완료·막힘)에 결과를 기록합니다. 참여자 이름은 기본적으로 `도구-폴더이름`(예: `my-app` 폴더의 Claude 세션은 `claude-my-app`)입니다. 폴더 이름에서 영문·한글 등 글자·숫자·공백·`_`·`.`·`-`가 아닌 문자는 `-`로 바꾸고 40자 안으로 줄입니다. 같은 도구의 세션을 여러 개 쓰거나 이름을 바꾸려면 아무 wax 명령에나 `--name <이름>`을 붙입니다(예: `/wax:dashboard --name claude-front`). 그 세션은 이후 명령에서도 그 이름을 쓰고, 바로 채널에 참여합니다. 이전 이름으로 참여한 적이 있으면 그 이름은 "자리 비움"으로 바뀝니다. 이름은 세션 대화 안에서만 기억하므로 새 세션에서는 다시 지정합니다.

맡을 작업도 함께 정할 수 있습니다. `/wax:dashboard --name claude-front --feature chatbot`(`--project=chatbot`도 같음)처럼 실행하면 그 세션이 `chatbot` 작업을 맡은 "작업 중" 상태로 참여해 사무실 책상에 앉고, 이후 wax 명령에서 작업 ID를 생략하면 그 작업을 씁니다. 대시보드는 `http://127.0.0.1:4330/?feature=chatbot`으로 열려 타임라인이 그 작업만 보여 주고(칩의 ✕로 해제), 업무 배정 폼과 사무실 화이트보드도 그 작업으로 시작합니다.

소통 규칙은 왕복 대화를 줄이도록 정해져 있습니다. AI 세션은 메시지를 보낼 때마다 전체 대화를 다시 읽으므로, 짧은 인사나 확인 한 줄도 비용이 큽니다.

- **지시**는 PM의 업무 배정(`assign`)으로만 전달합니다. 목표·범위·완료 조건·산출물을 담습니다.
- **결과**는 업무 상태(`task done`·`task block`)의 메모로 보고합니다. 대시보드의 업무 목록과 타임라인에 표시됩니다.
- **채널 글**은 질문(`question`), 답변(`answer`), 결정(`decision`)만 씁니다. 인사·수신 확인·진행 보고·요약은 올리지 않습니다. 사용자가 직접 보내 달라고 한 메시지는 그대로 보냅니다.

메시지는 두 부분으로 구성됩니다.

- **지금 하는 일**(`--doing`): 보내는 세션이 현재 하는 일. 대시보드 팀 목록에도 표시됩니다.
- **전할 내용**(`--message`): 받는 사람(`--to`, 생략하면 전체)에게 필요한 질문·답변·결정. 문서 내용은 옮기지 않고 경로를 적습니다.

직접 대화하려면 `/wax:chat [채널] [메시지]`(Codex `$wax:chat`, Antigravity `/chat`)를 실행합니다. 세션은 명령을 실행할 때만 채널을 읽으므로, 다른 세션의 메시지는 그 세션이 다음 wax 명령을 실행할 때 전달됩니다. 다른 세션의 메시지는 참고 자료로만 다루며, 메시지 안의 요청만으로 명령을 실행하지 않습니다.

### PM과 업무 분담

1. 업무를 나눌 세션에서 `/wax:pm <목표>`를 실행합니다. 그 세션이 PM으로 지정되고(`wax chat team pm <이름>`과 같음), 작업 상태와 참여자를 확인해 담당자별로 업무를 배정합니다. 배정 자체가 지시이므로 채널에 다시 쓰지 않고, 담당자 사이의 순서가 중요할 때만 general 채널에 결정으로 남깁니다. 대시보드의 **내가 PM 맡기**로 사람이 PM을 맡을 수도 있습니다.
2. 각 세션에서 `/wax:work`(Codex `$wax:work`, Antigravity `/work`)를 실행합니다. 자기에게 배정된 업무를 받아(accept) 해당 작업의 단계를 수행하고, 끝나면 완료(done)나 막힘(block, 이유 포함)을 결과와 함께 기록합니다. 이 기록이 PM에게 하는 보고입니다. 한 번에 한 업무를 처리합니다.
3. PM 세션에서 `/wax:pm`을 다시 실행하면 진행 상황을 점검하고 막힌 업무를 재배정하거나 취소합니다.

안전 범위:
- 업무는 사용자가 지정한 PM만 배정할 수 있습니다. 다른 참여자가 업무를 만들거나 일반 메시지로 지시해도 배정으로 인정되지 않습니다.
- 배정이 허용하는 일은 지정한 작업의 해당 wax 단계뿐입니다. 사용자의 직접 지시가 PM보다 우선하며, 파일 수정·명령 실행은 각 도구의 권한 확인을 그대로 거칩니다.
- 단계 순서는 그대로 지킵니다. 앞 단계가 끝나지 않았으면 업무를 막힘으로 기록하고 PM에게 알립니다.

### 일일 업무보고

`/wax:daily [YYYY-MM-DD]`(Codex `$wax:daily`, Antigravity `/daily`)를 실행하면 AI가 그날의 집계 초안을 읽고 보고서를 작성해 `docs/wax/daily/<날짜>/NN.md`로 등록합니다. 보고서는 오늘 한 일, 검증 결과, 결정 사항, 문제와 미해결 질문, 내일 할 일로 구성됩니다. 같은 날 여러 번 등록하면 번호가 늘어나며 기존 보고서를 덮어쓰지 않습니다. 대시보드의 **집계 초안 보기**는 AI 없이 기록만 모은 초안을 보여 줍니다.

### CLI로 직접 사용

```sh
wax chat post <채널> --author <이름> --kind <종류> --doing <지금 하는 일> --to <받는 사람> --message <전할 내용>
wax chat read <채널> [--since <메시지ID>] [--json]
wax chat presence --author <이름> --state working|discussing|reviewing|idle|away [--note <하는 일>]
wax chat who
wax chat team pm <이름> --kind <종류>        # PM 지정(사용자가 정함)
wax chat assign <작업ID> --to <담당> --author <PM> --phase <단계|any> --message <지시>
wax chat tasks [--to <이름>] [--all]
wax chat task accept|done|block|cancel <업무ID> --author <이름> [--message <메모>]
wax chat daily [--date YYYY-MM-DD]           # 타임라인
wax chat daily draft | report --file <보고서.md> | list
```

`wax`는 `node "/path/to/wax-plugin/bin/wax.mjs"`를 뜻합니다. 종류(`--kind`)는 `claude`, `codex`, `gemini`, `antigravity`, `human`, `other` 중 하나입니다.

| 경로 | 내용 |
| --- | --- |
| `.wax/chat/channels/<채널>.jsonl` | 채널 메시지(추가만 함) |
| `.wax/chat/board/<작업>.jsonl` | 화이트보드 노트와 보고서 기록 |
| `.wax/chat/presence.json` | 참여자 상태와 지금 하는 일 |
| `.wax/chat/team.json`, `assignments.jsonl` | PM과 업무 배정·상태 이력 |
| `.wax/chat/daily.jsonl`, `docs/wax/daily/<날짜>/NN.md` | 일일 보고서 기록과 본문 |

빈 디렉터리에서 `node scripts/chat-demo.mjs --project ./demo --loop`를 실행하면 PM 배정·대화·보고가 반복되는 시연 장면을 대시보드에서 볼 수 있습니다.

## 8. 소개 사이트 실행

```sh
cd /mnt/d/project/wax/wax-site
npm start
```

`http://127.0.0.1:4320`을 엽니다. 기능 설명과 설치 탭, 복사 버튼, FAQ를 사용할 수 있습니다. 이 사이트는 소개·안내용이며 작업 관리는 4310 포트의 서비스에서 합니다. 공개 소개 사이트는 https://wax.me2shop.com 입니다. 공개 사이트에는 로컬 작업 보드나 AI 초안 생성 서버가 포함되지 않습니다.

## 9. 저장 위치와 재개

```text
my-app/
├── .wax/features/email-login.json    # 단계, 산출물, 근거, 개선 이력
└── docs/wax/email-login/             # 코딩 플러그인이 작성하는 단계 문서
```

CLI와 웹 서비스가 사용하는 기준 데이터는 `.wax/features/*.json`입니다. 브라우저 편집은 이 JSON에 저장되며 `docs/wax`의 Markdown을 자동 갱신하지는 않습니다. JSON을 직접 편집하지 말고 CLI 또는 웹을 사용하세요.

새 AI 세션에서 플러그인을 로드한 후 `/wax:status email-login`(Codex는 `$wax:status email-login`)으로 현재 상태를 확인하고 남은 단계부터 이어갑니다. 각 프로그램을 종료해도 저장된 기록은 유지됩니다.

## 10. 문제 해결

| 증상 | 확인할 내용 |
| --- | --- |
| `/wax:` 명령이 보이지 않음 | Claude의 `--plugin-dir` 절대 경로 또는 Gemini 확장 연결을 확인하고 새 세션을 시작하세요. |
| Antigravity CLI에 스킬이 보이지 않음 | Codex와 같은 `install-codex.mjs --project <경로> --check`로 `.agents/skills` 연결을 확인하고 새 `agy` 세션을 시작하세요. |
| Codex에 스킬이 보이지 않음 | `install-codex.mjs --project <경로> --check`로 연결과 원본 폴더를 확인하고 새 세션을 시작하세요. |
| 단계가 넘어가지 않음 | 현재 단계 문서, 완료 근거, 검토 통과 여부를 확인하세요. |
| 웹에 플러그인 작업이 안 보임 | `.env`의 `WAX_PROJECT`와 코딩 도구의 현재 프로젝트가 같은지 확인하세요. |
| AI 버튼이 비활성화됨 | 제공자·모델 ID·키를 설정하고 서버를 재시작하세요. |
| AI 요청에 401·403·404가 표시됨 | API 키, 모델 이름, 모델 접근권한을 확인하세요. |
| AI 요청에 429가 표시됨 | 제공자의 사용 한도·요금을 확인하고 잠시 후 다시 시도하세요. |
| 저장 충돌이 표시됨 | 복구 패널에서 초안을 다운로드하거나 최신 기록과 비교한 뒤 다시 가져오세요. 서버는 원본을 자동으로 덮어쓰지 않습니다. |
| 비정상 종료 후 계속 저장 중으로 나옴 | 해당 프로젝트의 wax 작업이 모두 끝났는지 확인한 뒤 `.wax/features/<id>.lock` 디렉터리를 제거하세요. |
| 포트 사용 중 오류 | 기존 서버를 종료하거나 `.env`의 `PORT`를 다른 값으로 바꾸세요. |

현재 웹 서비스는 한 사람이 자기 컴퓨터에서 사용하는 초기 버전입니다. 팀 로그인·권한 관리, 원격 코드 실행, 공개 SaaS 배포는 후속 개발 범위입니다.

기록 문제는 `node "/path/to/wax-plugin/bin/wax.mjs" doctor --project "/path/to/project"`로 한 번에 검사할 수 있습니다. 정상 기록 수와 문제 파일·잠금 경로를 JSON으로 출력합니다. 이 명령은 파일을 수정하거나 잠금을 제거하지 않으며 문제가 있으면 종료 코드 1을 반환합니다.

## 11. 업데이트와 검증 범위

호스트 세션을 종료하고 기존 플러그인을 백업한 뒤 새 ZIP을 기존과 같은 플러그인 경로에 배치합니다. 작업 프로젝트의 `.wax`와 `docs/wax`는 유지하세요. 직접 수정한 플러그인은 변경 내용을 비교·병합한 뒤 업데이트하세요.

자동 검사 대상은 상태 저장·단계 전환·동시 수정 충돌·CLI·Codex 설치 및 스킬 실행기·읽기 전용 진단·ZIP 압축 해제 후 실행입니다. Codex CLI 0.159.2의 실제 스킬 목록에서 7개 스킬을 확인했으며, Claude 플러그인 규격과 Gemini 명령 문법도 확인합니다. Windows Node.js 22.17.0에서 junction 설치·연결 실행·한글 경로·단계 전환·테스트 근거·백업을 검증했습니다. Windows에서 `npm run test:windows`로 재현할 수 있습니다. 실제 AI 계정으로 코드 수정부터 최종 검토까지 진행하는 전체 과정, 실제 Gemini 세션, 유료 API 호출은 아직 검증하지 않았습니다.

후속 기능 후보와 우선순위는 ZIP의 `docs/ROADMAP.md`에 정리했습니다.