원문 캡처 · github.com
원문 캡처 · github.com

lights-on-software-factory는 Claude Code로 소프트웨어 공장을 운영하기 위한 출발점이자 교육용 예제 저장소다. 제작자는 Votito에 적용한 설정을 바탕으로 만들었으며, 오케스트레이터가 기본적인 Claude 워크플로 실행 방식보다 토큰 사용량을 약 80% 줄였다고 설명한다.

저장소는 새 프로젝트용 기본 설정과 소프트웨어 공장의 핵심 개념을 보여주는 예제를 제공한다.

  • Claude Code를 호스트와 작업 공간 디렉터리만 공유하는 안전한 환경에서 실행하는 샌드박스·컨테이너 설정은 CONTAINER.md에 설명돼 있다.
  • 결정론적 Bash 명령 조정기는 명령을 자세히 검사하고 프로젝트별 규칙에 따라 자동으로 승인하거나 거부한다. 명령을 차단할 때는 대신 해야 할 작업도 안내해 승인 요청에 지치는 일을 줄이고, 에이전트가 허용된 명령을 실행하도록 한다. 승인 요청이 발생할 때마다 Claude에 사용자 지정 규칙을 추가해 달라고 요청할 수 있다. 자세한 내용은 REGULATOR.md에 있다.
  • 결정론적 린터 기반 피드백 시스템은 사용자 지정 도메인 규칙을 적용해 코드 리뷰에 필요한 사람의 개입을 줄이는 것을 목표로 한다. PostToolUse 훅이 Claude가 수정하는 모든 JavaScript 파일에 린터를 실행하고, 흔히 발생하는 실수를 피할 수 있도록 오류 메시지로 에이전트를 안내한다. 반복해서 설계·코드 피드백을 제공하게 될 때마다 Claude에 사용자 지정 규칙을 작성해 달라고 요청할 수 있다. HTML·CSS 등 다른 파일 형식에 사용할 ESLint 언어 파서도 구현하도록 요청할 수 있다. 자세한 내용은 LINTER-HOOK.md를 참고하면 된다.
  • 기본 계획·구현 워크플로는 형식 설명과 오케스트레이터의 기반으로 삼기 위해 단순하게 만든 예제다. 저장소는 이를 자체 명령이나 더 복잡한 규칙으로 바꿔 사용하는 편이 좋다고 안내한다. 설명은 WORKFLOW.md에 있다.
  • 결정론적 다중 에이전트 Claude 워크플로 스크립트 생성기는 구현 워크플로가 만든 계획을 바탕으로 Claude 워크플로 스크립트를 만들고, 테스트와 게이트를 구성한다. 기계적인 오케스트레이션 작업에 추론 토큰을 낭비하지 않도록 하고, 일반적인 워크플로 오케스트레이션 작업을 추론(LLM)에서 결정론적 도구(명령줄)로 옮겨 워크플로 생성 속도를 높이고 토큰 사용량을 크게 줄인다는 설명이다. 자세한 내용은 ORCHESTRATOR.md에 정리돼 있다.

workspace 디렉터리에는 Claude Code 설정과 간단한 예제 프로젝트가 들어 있다. 컨테이너를 설정하고 첫 변경을 실행하려면 GETTING-STARTED.md부터 보면 된다. 빠른 개요는 gojko.net/slides/202609-gotocph.pdf에서 확인할 수 있다.

저장소의 최상위에는 시작 안내, 설정·린터 훅·명령 조정기·오케스트레이터·워크플로·컨테이너 안내 문서와 컨테이너 관련 makefile이 있다. vm/Dockerfile은 Alpine, Node.js, make, git 등이 포함된 컨테이너 이미지를 정의한다. .claude-home/은 Git에서 제외되며 컨테이너의 Claude Code 로그인 정보와 기록을 보관한다.

workspace/에는 Claude Code용 CLAUDE.md와 작업 공간 규칙을 담은 CONTRIBUTING.md, 훅·환경·권한·설정을 지정하는 .claude/settings.local.json, 워크플로 작업자·게이트·검사 에이전트가 있다. 명령에는 영향 분석, 계획 실행, 실행, 조정기가 포함된다. .claude/workflow/에는 계획 표기법과 생성기 참고 문서, 도구용 package.json, 훅 진입점과 명령줄 도구, 조정기·생성기·린터 코드 및 테스트가 있다. 그 밖에 계획과 진행 기록을 두는 plans/, 교체용 샘플 모듈 src/format-greeting.js, 테스트 파일, ESLint 설정, 프로젝트용 makefile과 패키지 파일이 들어 있다.

추가 안내 문서는 GETTING-STARTED.md에서 컨테이너 설정과 첫 변경을, SETTINGS.md에서 workspace/.claude/settings.local.json의 훅·환경·권한·설정을 다룬다. LINTER-HOOK.md는 수정 시 실행되는 린터 훅과 예제 규칙 두 개, 규칙 작성법을 설명한다. REGULATOR.md는 조정기의 판단 방식과 역할, 주요 규칙, 판단 진단·설정·규칙 추가를 안내한다.

WORKFLOW.md에는 /impact-analysis, /plan-execution, /execute 명령을 사용하는 흐름과 실행 감시·재개, /regulator, 작업 예제가 담겼다. ORCHESTRATOR.md는 오케스트레이터의 구성 요소와 명령줄 도구, 에이전트, 게이트 목표, 진행 기록과 재개를 다룬다. CONTAINER.md는 컨테이너 이미지와 실행 목표, 마운트, 재정의 설정, 컨테이너 내부에 node_modules를 유지하는 방법과 문제 해결을 설명한다. 계획 표기법과 실행 구조, 응답 형식, 오류 목록은 워크플로 README에서 확인할 수 있다. 저장소 라이선스는 MIT이며, LICENSE에 명시돼 있다.