fernbrook-labs/beginner-reference-book

초보자용 참고서(입문 가이드) 만들기

프로그래밍 언어나 프레임워크의 입문 참고서를, 지금까지 만든 TypeScript・Rust・Angular・Go 입문 가이드(견본은 references/examples/)와 동일한 디자인・동일한 기능・동일한 진행 방식으로 만듭니다. 완성되는 것은 다음 2가지입니다.

• 데스크톱에 놓는 단일 HTML 파일(OO입문가이드.html. 더블클릭으로 열 수 있음)
• claude.ai의 공유 페이지(비공개. 사용자가 Share 메뉴에서 공유함). Artifact 도구를 사용할 수 있는 환경(Claude Code 등)에서만 만듭니다.

동일한 디자인을 유지하기 위해, 모양과 동작은 이 스킬의 부품(assets/와 scripts/)을 그대로 사용합니다. 매번 CSS나 JavaScript를 다시 작성하지 마십시오. 작성하는 것은 본문(원고)과 언어에 맞춘 코드 확인 방법만입니다.

참고서의 가장 큰 가치는 '실린 코드와 결과가 정말로 올바르다'는 점에 있습니다. 코드 예제・오류 메시지・실행 결과는 반드시 실제 컴파일러나 공식 Playground에서 확인한 것을 싣습니다(상상으로 작성하지 않음). 버전이나 새 기능의 설명도 공식 릴리스 노트 등에서 확인한 후에 작성합니다.

작업은 몇 시간이 걸리는 긴 작업입니다. 매 단계마다 무엇을 하고 있는지 1~2문장으로 사용자에게 전달합니다.

1. 입력 확인하기

입력은 스킬 이름 뒤에 적힌 문자열(이 스킬의 본문 끝에 ARGUMENTS:로 붙어 있는 경우가 많음) 또는 사용자 요청 문장 안의 언어명・프레임워크명입니다.

• 아무 것도 적혀 있지 않은 경우: 작업을 시작하지 않고, "어떤 프로그래밍 언어・프레임워크의 참고서를 만드시겠습니까?"라고 되묻습니다(AskUserQuestion에 Python・Java・React・Vue.js 등의 후보를 최대 4개까지 제시합니다. 그 외는 "Other"로 자유롭게 적을 수 있도록 합니다).
• 프로그래밍 언어나 프레임워크 이외의 것이 적혀 있는 경우: 그 이유를 1문장으로 전달하고, 언어나 프레임워크를 다시 입력받습니다. 다시 입력된 것도 동일하게 확인하여 올바른 것이 입력될 때까지 진행하지 않습니다.
• 판단이 애매한 것・표기 변동・복수 지정의 처리와 전달 문장 예시는 references/questions.md의 "입력 확인 방법"에 있습니다. 망설여지면 반드시 읽습니다.

AskUserQuestion을 사용할 수 없는 환경에서는 같은 내용을 문장으로 물어보고 거기서 멈춥니다.

2. 질문 전에 사전 조사하기

선택지의 설명을 올바르게 작성하기 위해, 질문 전에 다음 사항을 확인합니다(몇 분 안에 끝냅니다. 큰 다운로드는 아직 하지 않습니다).

1. 최신 안정판 버전과 공개일: 공식 사이트나 릴리스 노트에서 확인합니다. 참고서의 "OO 대응"에 사용합니다.
2. **공식 Playground(브라우저에서 실행할 수 있는 공식 사이트)**가 있는지. 있다면 외부에서 보내 컴파일・실행할 수 있는 창구가 있는지, URL에 코드를 넣어 열 수 있는지, 공유 링크(서버에 코드를 저장하는) 방식인지.
3. 컴퓨터에 이미 설치되어 있는지(python --version 등으로 확인). 설치되어 있지 않다면 임시로 설치할 경우의 크기(공식 다운로드 크기).
4. 디스크 여유 공간(Windows PowerShell에서는 Get-PSDrive C, Git Bash에서는 df -h /c, macOS・Linux에서는 df -h ~).
5. 사용자 환경의 규칙(CLAUDE.md・AGENTS.md 등). 예를 들어 "클라우드와 동기화 중인 폴더(OneDrive 등)는 건드리지 않는다"와 같은 규칙이 있으면 사전 조사부터 정리까지 지킵니다.

조사 방법과 언어별 확인 방법의 후보는 references/verification.md에 있습니다.

3. 선택 항목 묻기(지금까지와 동일한 항목)

AskUserQuestion으로 다음 4가지를 한 번에 묻습니다. 항목과 선택지의 작성 방식은 지금까지 참고서를 만들 때와 동일하게 합니다(문장 템플릿은 references/questions.md). 추천 선택지를 맨 앞에 두고 "(추천)"을 붙입니다. AskUserQuestion이 없는 환경(Codex 등)에서는 같은 4가지 질문과 선택지를 번호 붙인 문장으로 제시하고(범위의 장 구성도 덧붙여 씀), 답변을 기다립니다.

1. 예상 독자: 예: "JS/TS 경험자(추천)", "프로그래밍 초보자". TypeScript를 기반으로 하는 프레임워크(Angular・NestJS 등)라면 "TypeScript 경험자(추천)", Python 프레임워크(Django 등)라면 "Python 경험자(추천)"처럼 대상에 맞춥니다.
2. 범위: "기본만(짧게・89장)", "기본 + 자주 사용하는 기능(추천・1214장)", "응용까지(길게・16~18장)". 각각 미리보기에 장 구성을 써서 보여줍니다.
3. 형식: "지금까지와 같은 형태(추천)" = 데스크톱에 단일 HTML 파일 + 공유 페이지, 확인 문제・코드 복사・읽은 장 기록・키워드 검색 포함. 그 외에 "HTML 파일만", "기능 선택". 공유 페이지를 만들 수 없는 환경(Artifact 도구 없음)에서는 "지금까지와 같은 형태"는 HTML 파일만이 됩니다. 그 경우 "HTML 파일만"을 제시하지 않고 설명에도 공유 페이지를 쓰지 않습니다.
4. 확인 방법: 사전 조사 결과에서 사용 가능한 방법만 나열합니다. "공식 Playground에서 확인", "임시로 설치하여 확인", "이미 설치된 OO으로 확인" 등. 디스크 여유 공간이 적을 때는 컴퓨터에 아무 것도 설치하지 않는 방법을 추천으로 합니다.

답변에 따라 계속해서 한 번만 더 묻습니다.

• "기능 선택" → 장 말미 확인 문제・코드 복사 버튼・읽은 장 체크・용어・키워드 검색을 다중 선택으로 묻습니다.
• 확인에 사용하는 Playground가 "공유 링크 방식"(Go Playground처럼 코드를 서버에 저장하여 링크를 만드는)이라면, "공유 링크 만들기" 또는 "복사해서 붙여넣기"를 묻습니다. 공유 링크는 외부 공개가 되며 삭제할 수 없으므로 반드시 승낙을 받습니다. URL에 코드를 넣어 열 수 있는 Playground(Rust・TypeScript)는 저장하지 않으므로 묻지 않아도 됩니다.

선택된 내용은 이후 작업에서 모두 지킵니다. 한 번 물어본 것을 다시 묻지 않습니다.

4. 계획 세우기

1. 장 구성을 결정합니다(references/writing-guide.md). 1장 10분 전후로 읽을 수 있는 분량. 언어라면 마지막 장은 "자주 보는 오류 읽는 법"으로 합니다. 과거 4권의 장 구성은 references/past-books.md에 있습니다.
2. spec.json을 작성합니다(references/book-spec.md에 항목과 예시가 있습니다). 표지 이름, 버전, 예상 독자, 장 제목, 코드 언어, Playground 여는 방법, 특색(브랜드 컬러) 등.
3. 특색은 해당 언어나 프레임워크의 공식 브랜드 컬러를 사용합니다. scripts/make_palette.mjs가 1색에서 라이트와 다크 색상을 만들고, 글자를 읽을 수 있는 대비인지도 확인합니다(new_book.mjs가 자동으로 호출).

5. 템플릿 만들고 원고 작성하기

1. 작업 폴더는 세션의 임시 폴더(Claude Code의 scratchpad 등. 없으면 OS의 임시 폴더 안에 새로 만든 폴더) 안에 만듭니다. 클라우드와 동기화 중인 폴더(OneDrive 등) 아래에는 만들지 않습니다.
2. 템플릿 만들기: node <이 스킬>/scripts/new_book.mjs <책 폴더> --spec spec.json
   • book.json・palette.json・src/body.html・src/ja-errors.json이 생성됩니다.
   • src/body.html의 목차・표지・사용법・장 프레임・확인 문제 프레임・부록 프레임은 이미 만들어져 있습니다. <!-- TODO … -->를 모두 다시 작성합니다(남아 있으면 조립 시 "수정 필요"가 됩니다).
3. 작성을 시작하기 전에 견본을 읽습니다. references/examples/에는 지금까지의 4권에서 표지・사용법・대표적인 1장・오류 장・부록을 발췌한 원고가 있습니다(모두 이 스킬의 부품으로 조립하여 확인 완료). references/examples/README.md의 표에서 만들 대상에 가까운 것을 1~2권 선택하여 body.html을 읽습니다(언어라면 go와 rust, TypeScript 기반 프레임워크라면 angular와 typescript 등). 규칙을 말로 읽는 것보다 실제 사례를 보는 편이 문장의 톤・설명 깊이・절 크기・코드 예제 제시 방식・확인 문제의 세분화가 일치합니다. 단, 모방하는 것은 작성 방식뿐이며 버전이나 기능 등의 사실은 반드시 다시 확인합니다. 견본 문장을 복사하여 단어만 바꾸지 않습니다.
4. 원고를 작성합니다. 부품(강조 상자・표・절차・확인 문제・오류 제목 등)의 HTML은 references/components.md, 코드 예제 작성법은 references/code-blocks.md, 문장 작성법은 references/writing-guide.md를 따릅니다. 장 수가 많으므로 몇 장씩 작성한 후 조립하여 확인하는 것이 좋습니다.

6. 코드 예제 확인하기

node <이 스킬>/scripts/build.mjs extract <책 폴더>   # 코드 예제를 work/에 추출
node <이 스킬>/scripts/checkers/go-playground.mjs <책 폴더>   # 언어에 맞는 확인 스크립트(아래 표)
node <이 스킬>/scripts/build.mjs render <책 폴더>    # 결과를 붙여 dist/에 HTML 생성

확인 스크립트	사용 상황
checkers/go-playground.mjs	Go. 공식 Go Playground에서 컴파일・실행・go vet・gofmt. --share로 공유 링크 생성
checkers/rust-playground.mjs	Rust. 공식 Rust Playground에서 컴파일・실행・타입 힌트
checkers/typescript-local.mjs	TypeScript/JavaScript. 임시로 설치한 TypeScript로 오류(공식 일본어 번역 포함)・말풍선・실행
checkers/local-command.mjs	Python・Java・C# 등. 로컬(또는 임시로 설치한) 명령어로 확인・실행

여기에 없는 언어나 프레임워크(Angular처럼 화면 표시까지 포함하려는 것 등)는 동일한 형식의 결과(work/results.json)를 출력하는 확인 스크립트를 새로 만듭니다. 결과 형식은 references/code-blocks.md, 제작 방법의 사고 방식과 과거 예시는 references/verification.md에 있습니다.

• render가 "수정 필요: 없음"이 될 때까지 수정합니다. 오류를 싣는 예제에는 행에 // ❌(경고는 // ⚠)를 적어 두면 조립할 때마다 예상대로 오류가 나오는지 확인할 수 있습니다.
• dist/report.txt를 읽고 오류 메시지・실행 결과・타입 표시가 본문 설명과 일치하는지 확인합니다.
• 임시로 설치한 것은 세션의 임시 폴더 안에만 설치하고 캐시의 위치도 그쪽으로 향하게 합니다(references/verification.md).

7. 화면에서 확인하기

scripts/test_guide.py를 실행합니다. dist/는 이 스크립트가 127.0.0.1의 지정된 포트에서 제공합니다.

python <이 스킬>/scripts/test_guide.py --book <책> --port 8770 --search "<본문에 나오는 단어>"

• Python의 Playwright와 Chromium이 필요합니다. 설치되어 있지 않다면 설치해도 되는지(합계 수백 MB)를 사용자에게 확인합니다. 설치할 수 없을 때는 이 확인을 건너뛰고 그 사실을 보고서에 기재합니다.
• 모두 합격할 때까지 수정합니다. 그 후 <책>/shots/의 스크린샷(표지・사용법・각 장・빠른 참조・다크・모바일)을 눈으로 보고, 내용 잘림・읽기 어려운 색・깨짐이 없는지 확인합니다.
• 본문의 외부 링크가 열리는지와 Playground 링크가 올바르게 열리는지(1개는 실제로 열어서 실행해 봄)도 확인합니다.

8. 전달하고 정리하기

1. 공유 링크를 만들기로 했다면 본문이 확정된 후에 만들고(--share), 모든 링크가 올바른 코드를 여는지 확인합니다.
2. dist/full.html을 사용자의 데스크톱(Windows라면 C:\Users\<사용자>\Desktop, macOS라면 ~/Desktop)에 <이름>입문가이드.html로 복사합니다. 같은 이름의 파일이 있을 때는 덮어쓰지 않고 사용자에게 확인합니다.
3. 형식에 공유 페이지가 포함되어 있고 Artifact 도구를 사용할 수 있는 환경이라면 quickstart를 호출한 후 dist/artifact.html을 공개합니다(icon은 book, description은 한국어로 1문장). 공개된 페이지는 비공개이며 공유는 사용자가 Share 메뉴에서 수행함을 전달합니다. 사용할 수 없는 환경에서는 이 절차를 건너뜁니다.
4. 임시로 설치한 것・캐시・스크린샷을 삭제합니다. 자신의 작업으로 공유된 장소(npm 캐시 등)에 쓴 것이 있으면 자신의 것만 확인하고 삭제합니다.
5. 한국어로 보고합니다: 저장 위치・공유 페이지 URL(만든 경우)・내용(장 구성 요점)・확인한 것(건수)・주의 사항(확인할 수 없었던 환경, Playground 제약 등).

참고 자료

파일	읽을 때
references/questions.md	입력 확인 방법과 선택 항목 묻는 방법(문장 템플릿)
references/book-spec.md	spec.json과 book.json 작성 방법
references/writing-guide.md	장 구성・문장 작성법・정확성 규칙
references/components.md	원고 HTML의 부품
references/code-blocks.md	코드 예제 작성법・속성・확인 스크립트 결과 형식
references/verification.md	언어별 확인 방법, 임시 설치 절차와 정리
references/past-books.md	지금까지의 4권 장 구성・색깔・확인 방법・발견한 점
references/examples/README.md	원고 견본(4권에서 발췌) 선택 방법. 원고 작성 전에 읽음