에이전트 제로프릭션 온보딩 — 한 명령으로 설치·검증·MCP배선·첫 레시피까지 (#4852)

[kevin9327]

무엇을 / 왜

에이전트는 사소하게 채택 가능한 도구를 기본값으로 고른다. 이 PR 은 rhwp 의 자발적 채택
레버로, "처음 보는 에이전트 → 설치·검증·MCP배선·첫 레시피까지"의 거리를 한 명령으로 줄인다.

python tools/agent_onboarding/rhwp_doctor.py (순수 Python 3 표준 라이브러리, 의존성 0) 하나가:

1. 바이너리 위치·버전 — PATH → target/release/rhwp 순으로 찾고 rhwp --version 확인. 없으면
   cargo build --release --bin rhwp 를 찍고 exit 3 으로 신호(긴 빌드를 대신 돌리지 않음).
2. 번들 샘플 자가검증 — samples/basic/english.hwp 로 info / export-text --json 을 돌려 구조
   출력을 확인. 통과를 위조하지 않는다 — 못 돌린 검사는 SKIP/FAIL 로 이유와 함께 보고.
3. 붙여넣기용 .mcp.json 방출 — rhwp mcp-serve. PATH 에 없으면 절대 경로를 채워준다.
   --write <경로>(기존 파일은 --force 없이 덮어쓰지 않음).
4. 첫 5분 레시피 지도 — 실존 스킬·레시피만 런타임 확인해 인용(트리아지·표 추출·서식 채우기·
   보안 스윕·작업 영수증).

--json 으로 기계 판독(stdout=리포트 JSON 하나), 종료 코드로 정상(0)/임계실패(1)/사용법(2)/
빌드필요(3)를 신호한다.

실제 닥터 출력 (이 저장소에서 실측)

바이너리를 빌드한 상태에서 python tools/agent_onboarding/rhwp_doctor.py:

rhwp doctor — 에이전트 제로프릭션 온보딩 점검
repo: .../rhwp-wt-onboard

[1] 바이너리 위치·버전
  [PASS] rhwp 발견: .../target/release/rhwp.exe  (source: target/release)
  [PASS] 바이너리 버전: rhwp --version
           → rhwp v0.8.4
  [PASS] 자가검증: info: rhwp info ".../samples/basic/english.hwp" --json
           → format=hwp5, pageCount=1, version=5.0.3.0
  [PASS] 자가검증: export-text: rhwp export-text ".../samples/basic/english.hwp" --json --max-chars 2000
           → pageCount=1, pages=1, 본문문자=1281

[2] 붙여넣기용 .mcp.json  (호스트 프로젝트 루트에 두거나 mcpServers 키를 병합)
  { "mcpServers": { "rhwp": { "command": "<절대경로>/rhwp.exe", "args": ["mcp-serve"] } } }

[3] 첫 5분 레시피 지도 (실존 스킬·레시피만 인용)
  · 문서 트리아지 …   스킬: rhwp-doc-triage [OK]
  · 표 추출 …         스킬: rhwp-table-exchange [OK]   레시피: recipes/02_… [OK]
  · 서식 채우기 …     스킬: rhwp-form-fill [OK]        레시피: recipes/01_… [OK]
  · 보안 스윕 …       스킬: rhwp-security-sweep [OK]   레시피: recipes/10_… [OK]
  · 작업 영수증 …     스킬: rhwp-work-receipt [OK]

판정: 정상 — 바로 붙여도 됩니다  (exit=0)

우아한 저하(바이너리 미빌드): 크래시·행 없이 [FAIL] rhwp 미발견 … cargo build --release --bin rhwp
를 찍고 .mcp.json 은 command:"rhwp" (PATH 형)로 방출, exit 3. --json 은 stdout 에 순수 JSON
하나만 낸다(실측 파싱 OK, exit 0).

5분 경로

1. cargo build --release --bin rhwp (최초 1회)
2. python tools/agent_onboarding/rhwp_doctor.py
3. 방출된 .mcp.json 을 호스트 루트에 붙임(또는 --write)
4. 첫 레시피 표(과제 → 명령 → 스킬 → 레시피)에서 하나 실행

정본: mydocs/manual/agent_onboarding.md.

변경 파일 (새 파일만)

• tools/agent_onboarding/rhwp_doctor.py — 닥터 + 부트스트랩
• tools/agent_onboarding/test_rhwp_doctor.py — 바이너리 불요 가드 테스트(16건)
• mydocs/manual/agent_onboarding.md — 5분 경로 문서(한글)
• .claude/skills/rhwp-onboarding/SKILL.md — 얇은 온보딩 스킬(닥터·문서로 라우팅)

src/** · MCP 서버 모듈 · gym/tools/** · main.rs/CLI 디스패치 · 기존 명령 파일 · ci.yml 은
건드리지 않았다(병렬 세션 소유 표면).

검증 (이 머신에서 실측)

• 닥터 end-to-end: 바이너리 빌드 후 전 검사 PASS · exit 0(위 출력).
• 우아한 저하: 빈 repo-root 로 exit 3, 크래시·행 없음. --write 덮어쓰기 보호 exit 2, --force 로 0.
• 가드 테스트: python -m unittest tools/agent_onboarding/test_rhwp_doctor.py → 16 passed
  (바이너리 불요: .mcp.json 방출·집계 종료코드·레시피 실존·샘플 선택).
• 문서 링크: python scripts/check_markdown_links.py 두 신규 md 통과(이상 없음).
• Python + Markdown 만 변경 — rustfmt 불요.

후속 (이 PR 범위 밖)

• CI 배선: 가드 테스트를 lint 잡의 python unittest 목록에 한 줄로 추가하면 매 PR 에서 돈다.
  현재 그 영역을 병렬 세션들이 활발히 편집 중이라 앵커 충돌을 피해 이 PR 에서는 뺐다 — 별도
  1줄 배선 PR 로 남긴다.
• Rust 하위명령: rhwp onboard(닥터를 CLI 표면으로 승격)가 더 나을 수 있으나 main.rs/
  디스패치 소유 충돌을 피해 이번엔 Python + docs 로 유지한다.

Closes #4852

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[jangster77]

통합 PR #4883(4412546)로 병합 완료했습니다.

원 head와 CI를 다시 확인해 누적 반영했고, 상세 검토·메인터너 보정·검증 근거는 archive 검토 기록에 남겼습니다.

중복 병합을 막기 위해 이 원 PR을 닫습니다. 감사합니다.

[jangster77]

통합 PR #4883(4412546)로 병합 완료했습니다.

원 head와 CI를 다시 확인해 누적 반영했고, 상세 검토·메인터너 보정·검증 근거는 archive 검토 기록에 남겼습니다.

중복 병합을 막기 위해 이 원 PR을 닫습니다. 감사합니다.