Claude Code 위에서 실행되는 장편 웹소설 창작 플러그인입니다. 초기 설정, 권(卷) 구성 계획부터 장(章) 집필, 검토, 기억 축적, 상태 조회, 그리고 읽기 전용 시각화 패널에 이르기까지—전체 창작 프로세스가 하나로 연결되어 있습니다.

이 도구가 해결하고자 하는 핵심은 단 하나입니다: AI가 수백 장을 써 내려가더라도 설정을 기억하고, 복선을 이어가며, 대강(Outline)을 유지하게 만드는 것.

한 줄 정의: 이것은 장편 연재를 위한 일관성 시스템(Consistency System)이며, 쓰고 나면 잊어버리는 일회성 생성기가 아닙니다.

v7 리팩토링 RFC 공시 중 차세대 v7 설계가 공개 의견 수렴 단계에 진입했습니다. Discussions #118: v7 설계 공시를 읽고 피드백을 남겨주세요. Issue 섹션만 확인하는 사용자는 Issue #119: v7 공시 안내 게시글을 통해 접속할 수 있습니다. 기존의 "다음 단계 방향 투표"는 종료되었으며, 향후 우선순위는 RFC 피드백과 실시 계획을 기준으로 결정됩니다.

장편 창작에서 가장 어려운 것은 첫 장을 쓰는 것이 아니라, 80장, 200장 이후에도 다음 사항들을 유지하는 것입니다:

• 캐릭터 동기의 일관성 유지
• 전투력, 타임라인, 장소 및 세계관 규칙 간의 충돌 방지
• 복선의 기록, 전개 및 회수
• 재미 요소(爽点), 감정선, 세계관 확장의 리듬 유지
• 각 장을 쓴 후 사실(Fact)이 검색 가능한 상태 시스템으로 축적됨

이 시스템이 하는 일은 위와 같이 "반드시 기억해야 하고 무너져서는 안 되는" 제약 사항들을 Claude Code가 자동으로 실행하는 단계로 만드는 것입니다: 집필 전 자료를 조회하고, 집필 후에는 새로 발생한 사실을 기록하며 일관성 검토를 수행한 뒤, 최신 상태를 검색 인덱스, 장 요약, 장기 기억 및 대시보드(Dashboard)에 동기화합니다. 단순히 "쓸 줄 아는" 것이 아니라, 쓰면서 쌓아 나가는 것입니다.

flowchart LR
User[저자 / Claude Code] --> Skills[8개 Skill 명령]
Skills --> Agents[Context / Reviewer / Data / Deconstruction Agent]
...

v6.0.0의 기본 메인 체인은 Story System이며, 몇 가지 핵심 역할은 다음과 같습니다:

.story-system/
: 유일한 사실의 원천(Source of Truth)으로, 집필 전의 "계약"과 집필 후의 "커밋"이 모두 여기에 저장됩니다. 승인된 CHAPTER_COMMIT이 여기에 기록됩니다.

.webnovel/state.json, index.db, summaries/, memory_scratchpad.json:
: 모두 메인 체인에서 파생된 읽기 전용 뷰(Read-only view)로, 조회 및 전시용으로 사용됩니다.

.webnovel/projection_log.jsonl:
: 프로젝션 실행 로그로, state/index/summary/memory/vector 중 어느 경로가 동기화되지 않았는지 파악하는 데 사용됩니다.

project-status, doctor, preflight 및 Dashboard는 메인 체인과 실행 상태를 직접 보여주므로, 잘못된 부분을 한눈에 확인할 수 있습니다.

Claude Code Marketplace를 통해 설치:

claude plugin marketplace add lingfengQAQ/webnovel-writer --scope user
claude plugin install webnovel-writer@webnovel-writer-marketplace --scope user

현재 프로젝트에만 적용하고 싶다면 --scope user를 --scope project로 변경하세요.

python -m pip install -r https://raw.githubusercontent.com/lingfengQAQ/webnovel-writer/HEAD/requirements.txt

Claude Code에서 다음을 입력하세요:

/webnovel-init

초기화가 완료되면 다음과 같은 내용을 포함하는 소설 프로젝트 디렉토리가 생성됩니다:

project-root/
├── .story-system/ # 계약, 챕터 커밋 및 이벤트 감사 (Audit)
├── .webnovel/ # 상태, 인덱스, 요약, 백업 및 장기 기억 (Long-term Memory)
...

소설 프로젝트 루트 디렉토리로 이동하여 .env.example을

.env로

복사한 뒤 API Key를 입력하세요:

cp .env.example .env

최소 설정:

EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your_embed_api_key
...

Embedding Key를 입력하지 않아도 사용할 수 있습니다. 이 경우 시스템은 자동으로 BM25 키워드 검색으로 전환되지만, 의미론적 검색 (Semantic Retrieval) 성능은 다소 약해질 수 있습니다. Embedding과 Rerank는 모두 OpenAI 호환 인터페이스로 교체 가능합니다.

/webnovel-plan 1 # 제1권 계획
/webnovel-write 1 # 제1장 집필
/webnovel-review 1-5 # 제1-5장 검토
...

/webnovel-dashboard

Dashboard는 읽기 전용 패널로, 프로젝트 상태, 엔티티 관계도 (Entity Relationship Graph), 챕터 내용, 복선 (Foreshadowing) 및 독자 유지율 (Retention) 데이터를 확인할 수 있습니다. 프론트엔드는 미리 패키징되어 플러그인과 함께 배포되므로, 로컬에서 npm build를 실행할 필요가 없습니다.

/webnovel-write

단순히 모델에게 작업을 던져 한 번 생성하고 끝내는 것이 아니라, 관문(Gate)이 포함된 완전한 파이프라인 (Pipeline)입니다:

• 프로젝트 루트, 플레이스홀더 (Placeholder) 및 Story System의 상태 점검
• 현재 챕터의 런타임 계약 (Runtime Contract) 갱신
• context-agent를 호출하여 집필 작업 지시서 생성 - 작업 지시서에 따라 본문 초안 작성
• reviewer를 호출하여 다차원 검토 수행 - 차단 이슈 (Blocking Issue)가 통과되지 않으면 중단 - 윤문 (Polishing), 편집, Anti-AI 최종 점검
• data-agent를 호출하여 사실 관계 추출 - CHAPTER_COMMIT 생성 - 상태(State), 인덱스(Index), 요약(Summary), 메모리(Memory), 벡터(Vector) 투영 (Projection) 구동 - 챕터 단위 백업 실행

이렇게 설계된 이유는 "어떻게 쓸 것인가"와 "무엇을 썼는가"를 분리하기 위해서입니다. 문체와 리듬은 자유롭게 발휘할 수 있지만, 발생한 사실 관계는 반드시 등록, 검토, 아카이빙되어야 하며 모호해서는 안 됩니다.

/webnovel-init, /webnovel-plan, /webnovel-write 및 /webnovel-review가 종료될 때마다 작가를 위한 최종 보고서가 제공되며, 내부 JSON, 트레이스백 (Traceback) 또는 긴 명령 로그를 직접 노출하지 않습니다. 보고서는 먼저 다음과 같이 한 줄의 총괄 상태를 제공합니다:

완료 (Completed): 목표 결과물과 주요 검증을 모두 통과하여 다음 단계로 진행할 수 있습니다. 부분 완료 (Partially Completed): 주요 결과물은 보존되었으나, 건너뛴 항목, 자동 처리 항목 또는 확인이 필요한 잔여 사항이 있습니다. 처리 필요 (Action Required): 시스템이 안전한 위치에서 멈췄으며, 창작 방향, 사실 관계 선택, 파일 덮어쓰기 여부 또는 차단 이슈(Blocking Issue) 처리에 대한 사용자의 결정이 필요합니다. 미완료 (Failed): 주요 결과물이 신뢰할 수 있게 생성되지 않았으므로, 보고서의 복구 제안에 따라 재실행하거나 원인을 파악하세요.

그 아래에는 세 가지 고정 섹션이 있습니다. 첫째는 생성된 파일과 완료 상황, 둘째는 과정 중 발생한 문제와 비정상 소요 시간, 셋째는 다음 단계 제안입니다. 시스템이 자동으로 처리한 내용(예: 투영 실패 후 재시도 성공 등)도 기록됩니다. 복구 불가능한 장애가 발생한 경우에만 .webnovel/logs/run_last.log를 확인하라는 메시지가 표시됩니다.

실행 중에는 현재 무엇을 하고 있는지, 무엇이 생성될 것인지 알려주는 소량의 진행 표시만 나타납니다. 창작 방향, 사실 일관성, 파일 덮어쓰기 위험 또는 차단 이슈(Blocking Issue)에 대한 판결이 필요한 경우에만 사용자에게 질문합니다. 동일한 /webnovel-write [챕터 번호] 명령을 반복 실행할 경우, 시스템은 먼저 신뢰할 수 있는 중단점 (Checkpoint)을 확인하여 최대한 실패 지점부터 재개하며, 이미 신뢰할 수 있게 완료된 본문, 검토, 커밋 또는 백업은 다시 작성하지 않습니다.

37개의 중국 웹소설 장르 템플릿이 내장되어 있으며, 여러 장르를 혼합하여 쓰는 것도 지원합니다. 아래는 그중 일부입니다:

전체 목록은 장르 템플릿 문서를 참조하세요.

모든 명령줄 도구(Command Line Tools)는 통합적으로 scripts/webnovel.py를 통해 실행됩니다.

실행 방법:

python -X utf8 "<CLAUDE_PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<PROJECT_ROOT>" <subcommand> [arguments]

주요 서브 명령(Subcommands):

더 많은 명령은 명령 상세 설명을 참조하세요.

저장소를 클론(clone)한 후 의존성을 설치하세요:

python -m pip install -r requirements.txt
python -m pip install -r webnovel-writer/scripts/requirements.txt

테스트 실행:

python -m pytest

대시보드(Dashboard) 프론트엔드는 webnovel-writer/dashboard/frontend/에 위치하며, 배포 버전에는 이미 dist/ 빌드 결과물이 포함되어 있습니다. 프론트엔드 개발 시에는 해당 디렉토리로 이동하여 별도로 실행할 수 있습니다:

npm install
npm run dev

사전 점검(preflight)을 우선 실행하세요:

python -X utf8 "<CLAUDE_PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<PROJECT_ROOT>" preflight
python -X utf8 "<CLAUDE_PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<PROJECT_ROOT>" doctor --format text

중점 확인 사항:

• story_runtime.mainline_ready가 true인지 확인
• .story-system/commits/chapter_XXX.commit.json 파일이 존재하고 accepted 상태인지 확인
• projection_status가 모두 done 또는 skipped인지 확인
• index.db, summaries/, memory_scratchpad.json이 정상적으로 생성되었는지 확인
• RAG API Key가 웹소설 프로젝트 루트의 .env 파일에 기록되었는지 확인

더 자세한 운영 설명은 프로젝트 구조 및 운영을 참조하세요.

Issue와 PR을 환영합니다. 저장소에 포함된 템플릿을 사용하는 것이 좋으며, 재현 단계, 환경 정보, 영향 범위 및 검증 방법을 작성해 주세요. 개인정보는 반드시 비식별화(masking)해야 함을 잊지 마세요.

권장 프로세스:

git checkout -b feature/your-feature
git commit -m "feat: add your feature"
git push origin feature/your-feature

기여하기 좋은 방향:

• 새로운 소재 템플릿 및 소재 규칙
• 더 강력한 챕터 검토 (Chapter Review) 차원
• 대시보드 (Dashboard) 정보 구조 및 시각화
• RAG 검색, 개체명 결합 해소 (Entity Disambiguation), 장기 기억 (Long-term Memory)
• Windows/macOS/Linux 호환성 문제
• 문서, 예제 프로젝트 및 초보자 튜토리얼

Webnovel Writer는 개인 시간을 활용하여 유지 관리됩니다. 만약 이 프로젝트가 설정 정리나 복선 맞추기 시간을 아껴주었다면, 아이디어를 공유하거나 사용 경험을 피드백하고, 또는 프로젝트 지원 의사를 밝히기 위해 언제든 연락해 주세요:

본 프로젝트는 GPL v3 라이선스를 사용합니다.

본 프로젝트는 Claude Code, Gemini CLI 및 Codex를 활용하여 Vibe Coding 방식으로 개발되었습니다.

영감의 원천: Linux.do 게시물

oh-story-claudecode에 감사드립니다.

텍스트 분석 (Deconstruction) 프로세스 참고를 제공했습니다.