claude-octopus 딥다이브
— 여러 AI의 의견을 실행 가능한 검증 절차로 묶기

1프로젝트 한줄 요약

claude-octopus는 같은 문제를 여러 AI에게 맡기고, 서로 다른 결과를 검토·통합하는 절차를 Claude Code에 붙이는 플러그인입니다. 조사, 요구사항 정의, 구현, 검증을 명령과 스킬로 제공하며 외부 CLI 또는 API로 모델을 호출합니다.

저장소 설명의 요지는 “같은 조사·설계·코딩 과제를 여러 모델에 맡기고, 출시 전에 의견 차이를 드러내자”입니다. 소스에서는 이 목표가 scripts/lib/workflows.sh의 단계별 함수, scripts/lib/run-contract.sh의 실행 기록, scripts/lib/council.sh의 심의 규칙으로 나뉩니다.

1-1. 사용자에게 보이는 네 단계와 내부 이름

네 함수는 scripts/lib/workflows.sh에 있습니다. 전체 순서를 묶는 함수는 embrace_full_workflow()입니다. 문서가 부르는 Double Diamond는 문제를 넓게 탐색한 뒤 좁히고, 해결책도 넓게 검토한 뒤 좁히는 흐름을 뜻합니다.

1-2. 처음부터 여러 계정이 필요한가?

README는 외부 제공자 없이 Claude만으로 시작할 수 있다고 설명합니다. 다만 다른 회사 모델의 독립적인 의견을 얻으려면 해당 제공자의 실행 도구와 인증이 필요합니다. 설치 가능한 연결 종류와 지금 사용할 수 있는 연결은 구분해야 합니다.

이 저장소에서 배울 핵심은 AI를 많이 호출하는 법보다, 호출 결과를 믿을 조건을 프로그램으로 표현하는 법입니다.

2왜 주목받는가

2026-10-23 GitHub 기준 스타 4,289개, 포크 404개이며 GitHub Trending Shell Monthly 13위로 선정됐습니다. 2026-01-15에 만들어졌고 최신 릴리스는 2026-10-22의 v11.15.0입니다. 이 수치는 관심도를 보여 주지만 실제 정확도나 도입 효과를 측정한 실험은 아닙니다.

2-1. 코드 생성 뒤의 “정말 맞는가?”를 다룬다

AI가 그럴듯한 설명을 생성해도 요구사항을 빠뜨리거나 없는 코드를 인용할 수 있습니다. 이 프로젝트는 독립적인 리뷰, 반론, 실행 결과 확인을 하나의 작업 흐름에 넣습니다. 특히 council_response_quote_verification_json()은 답변이 인용한 코드가 근거 파일이나 검토 대상 diff에 실제로 있는지 검사합니다.

이 함수는 scripts/lib/council.sh에 있으며 인용 주변의 코드와 파일 내용을 공백 정규화 후 비교합니다. 특정 길이·근접 범위의 인용을 검사하는 규칙 기반 장치이므로 답변 전체의 진실성을 증명하지는 않습니다. 그래도 “파일 경로가 존재한다”보다 강한 검증을 시도한다는 점이 학습할 만합니다.

2-2. 역할 수보다 의견의 독립성을 신경 쓴다

이름이 다른 세 에이전트가 같은 모델을 사용하면 같은 실수를 반복할 수 있습니다. Council 집계 코드는 응답 수와 함께 승인한 모델 계열의 다양성을 봅니다. 표준·심화 설정에서 필요한 독립 승인 계열 수가 모자라면, 응답이 여러 개여도 정족수를 통과하지 못할 수 있습니다.

2-3. 기존 작업 환경에 붙이는 방식

Claude Code에서는 슬래시 명령과 스킬로, MCP 클라이언트에서는 도구 호출로 접근합니다. 두 경로가 같은 scripts/orchestrate.sh를 이용하므로 기존 CLI를 버리고 새 웹 서비스로 옮겨야 하는 구조는 아닙니다. 실제 사용 가능 범위는 호스트·인증·제공자별 기능에 달려 있습니다.

위 표는 작업 방식의 차이를 비교한 것입니다. 특정 제품의 최신 전체 기능이나 성능 순위를 비교한 표는 아닙니다. README 역시 일상적인 요청에는 Claude 기본 기능을 쓰고, 독립 의견이나 더 엄격한 검토가 필요할 때 Octopus를 쓰도록 안내합니다.

이 프로젝트의 매력은 한 모델의 답을 다른 관점과 대조하고, 그 과정에서 생긴 실패와 이견을 기록한다는 데 있습니다.

2-4. 문서와 구현을 함께 읽어야 보이는 차이

3기술 스택 전체 지도

3-1. 실행 계층: Bash가 중심이다

루트 package.json의 main은 scripts/orchestrate.sh입니다. 루트 패키지에 런타임 dependencies 항목이 없고 devDependencies도 빈 객체입니다. 그렇다고 의존성이 없는 것은 아닙니다. Bash·Git·jq·Python·Node와 선택한 외부 CLI가 실행 환경을 이룹니다.

검사한 파일 목록에 Cargo.toml, go.mod, pyproject.toml, Dockerfile은 없습니다. 핵심 실행 경로를 Rust 서버·Go 서비스·컨테이너 앱으로 이해하면 코드 지도가 어긋납니다.

3-2. MCP 어댑터: TypeScript로 외부 도구 인터페이스를 만든다

버전은 mcp-server/package.json 기준입니다. ^가 붙은 값은 정확한 설치 버전이 아니라 허용 범위입니다. 저장소에 npm·pnpm·Yarn 잠금 파일은 없으므로 이 선언만으로 모든 전이 의존성의 실제 설치 버전을 고정할 수 없습니다.

3-3. 프론트엔드: 독립적인 웹 앱 대신 호스트 화면을 사용한다

핵심 제품에 React·Vue 기반 웹 프론트엔드는 없습니다. 사용자는 Claude Code의 대화·슬래시 명령, 외부 MCP 클라이언트, 터미널 출력으로 상호작용합니다. hooks/octopus-hud.mjs는 ANSI 색상으로 상태줄을 구성하고 작업 단계·비용·사용량 등을 표시하는 Node 코드입니다.

이 HUD의 설정에는 사용량 캐시 60_000ms, API 시간 제한 8000ms, 버전 확인 캐시 3_600_000ms가 있습니다. 주석에 적힌 응답 속도는 작성자의 설명이며 독립적인 성능 측정값으로 읽으면 안 됩니다.

별도 도구인 scripts/token-extraction/은 UI 디자인 토큰을 추출합니다. 이 패키지는 glob ^10.3.10, tinycolor2 ^1.6.0, 개발용 typescript ^5.3.3·vitest ^4.0.18을 선언합니다. Tailwind나 CSS 변수를 분석한다는 사실이 이 프로젝트 자체가 Tailwind 웹 앱이라는 뜻은 아닙니다.

3-4. 인프라·빌드: 생성물과 테스트 범위를 관리한다

Makefile의 sync는 README 동기화, 마켓플레이스 정보 생성, Factory용 스킬 생성 작업을 묶습니다. sync-check는 생성물이 최신인지 검사하고, ci-local은 여기에 스모크·전체 단위·통합 테스트를 연결합니다. 이름만 보고 명령을 실행하기보다 각 타깃이 무엇을 바꾸는지 먼저 읽어야 합니다.

.github/workflows/test.yml에는 Linux·macOS 스모크 테스트, 변경 범위에 따른 단위 테스트, 별도 Council 테스트, 심볼릭 링크 경로 검사, 패키지 무결성 검사가 있습니다. 이식성 검사에서는 Bash 4 전용 연관 배열과 nameref를 제한하고 GNU 전용 sed 사용도 찾습니다.

다른 워크플로인 .github/workflows/claude-octopus.yml의 수동 실행 작업은 Node 22, Claude Code 2.1.228을 지정합니다. 이는 그 CI 작업의 실행 버전이며 모든 사용자 환경의 최소 요구사항과 같은 수치는 아닙니다.

3-5. 직접 센 코드 규모

커밋 286ef4d의 Git 추적 파일 1,415개를 대상으로 확장자별 물리적 줄을 셌습니다. 빈 줄·주석·테스트·vendors/를 포함하고, dist/ 경로와 Git 내부 파일은 제외했습니다. 확장자가 없는 bin/ 실행 파일은 Shell 수치에 넣지 않았습니다. 따라서 순수 구현량이나 테스트 커버리지 수치가 아닙니다.

언어 비중보다 중요한 구분은, Bash가 실행을 맡고 TypeScript가 연결을 맡으며 파일 기반 기록이 둘 사이의 결과를 남긴다는 점입니다.

4아키텍처 심화 분석

4-1. 전체 시스템 구조도

도식은 주요 책임의 연결을 단순화한 것입니다. 모든 명령이 네 단계를 전부 거치지는 않습니다. 예를 들어 Council은 별도 심의 흐름이며, 진단 명령 일부는 scripts/orchestrate.sh의 초반 분기에서 무거운 작업 라이브러리를 로드하기 전에 처리됩니다.

4-2. 설계 패턴 ① 얇은 어댑터와 공통 실행 경로

mcp-server/src/index.ts의 runOrchestrate()는 작업 로직을 새로 구현하지 않습니다. 명령·프롬프트·프로젝트 경로·플래그를 받아 셸 진입점에 전달합니다. MCP 도구 octopus_develop은 내부 명령 tangle로 연결됩니다.

// runOrchestrate()의 핵심 부분을 발췌·축약
const args = [...flags, command, ...postFlags, prompt];
const effectiveProjectRoot = await validateProjectRoot(projectRoot);
const { stdout, stderr } = await executor(ORCHESTRATE_SH, args, {
  cwd: effectiveProjectRoot,
  timeout: 300_000,
  env: { /* 전달할 환경변수를 구성 */ },
});

핵심은 execFile에 실행 파일과 인자 배열을 따로 넘긴다는 점입니다. 프롬프트를 셸 명령문에 이어 붙이는 방식보다 셸 재해석 경계를 줄일 수 있습니다. 전역 플래그를 명령 앞에, 하위 명령 플래그를 뒤에 놓는 규칙도 이 함수가 책임집니다.

shared/adapter-runtime.mjs의 validateProjectRoot()는 절대 경로를 요구하고, 실제 경로를 해석하고, 디렉터리인지 검사하며 파일시스템 루트는 거부합니다. 다만 이 검사는 “허용된 프로젝트 목록”을 구현한 것은 아닙니다. 접근 가능한 다른 디렉터리까지 모두 격리하는 샌드박스로 오해하면 안 됩니다.

입력은 Zod 스키마로 설명하지만 내부 콜백의 ToolParams는 Record<string, any>입니다. strict: true 설정만으로 모든 내부 값의 타입 안전성이 자동 보장되는 것은 아니라는 점도 눈여겨볼 만합니다.

4-3. 설계 패턴 ② 레지스트리와 명시적인 실행 계획

scripts/lib/provider-registry.sh는 제공자 ID·별칭·명령·조직·기능을 하나의 표로 관리합니다. octo_provider_canonical()은 정확한 ID를 우선하고, 별칭을 확인한 뒤 가장 긴 ID 접두어를 선택합니다. 덕분에 claude-sdk-*가 더 짧은 claude로 잘못 해석되는 일을 피합니다.

# octo_provider_registry_rows()의 행 형식
# ID | 별칭 | 실행 명령 | 조직 | 지원 기능
codex|openai,gpt*|codex|openai|model-config,council,health,detect,dispatch,env
claude-sdk|claude-agent*|claude-agent|anthropic|model-config,health,detect,dispatch,env

정체성 표와 별도로 octo_provider_runtime_rows()에는 인증 방식·상태 확인 함수·모델 환경변수·컨텍스트 예산·격리 분류 등이 있습니다. 두 표의 ID가 맞아야 하는 계약을 두어 연결 정보를 한쪽에만 추가하는 실수를 찾습니다.

scripts/lib/dispatch-plan.sh의 octo_dispatch_plan_create()는 선택 결과를 JSON으로 고정합니다. 요청 모델과 해석된 모델, 선택 출처, 프로젝트·플러그인 경로, 도구 정책, 인자 배열, 입력·출력 예산, 마감 시각을 함께 기록합니다.

// 실행 계획의 필드 구조를 설명하기 위한 축약 예시
{
  "schema_version": 1,
  "provider": "codex",
  "selection_source": "resolved-policy",
  "argv": ["codex", "..."],
  "environment_names": ["OPENAI_API_KEY"],
  "credential_names": ["OPENAI_API_KEY"],
  "budgets": { "available_input_tokens": 12000 },
  "deadline_epoch": 0
}

이 예시는 실제 실행 결과가 아니라 필드 구조의 요약입니다. 코드가 기록하는 것은 자격증명 이름이며 값은 아닙니다. 인자에 자격증명 대입이 섞인 경우도 거부합니다. 실제 환경변수 전달은 별도 계층에서 구성합니다.

scripts/lib/command-argv.sh의 octo_dispatch_command_to_argv()는 제한된 명령 문자열의 따옴표와 공백을 직접 해석해 배열로 돌려줍니다. 여기서는 eval이나 명령 치환을 수행하지 않습니다. “사용자 요청 → 문자열 → 다시 셸 실행”의 위험을 줄이려는 설계입니다.

4-4. 설계 패턴 ③ 상태 머신과 실행 이력 원장

scripts/lib/run-contract.sh는 스키마 버전 10.0의 실행 계약을 정의합니다. 각 모델의 한 번의 참여를 seat로 추적하며 octo_run_transition_valid()가 허용된 상태 이동을 검사합니다.

run_contract_transition()은 output_received·validated로 전이할 때 출력 파일의 사용 가능 여부를 확인합니다. 공백뿐인 파일과 단순 가용성 응답은 거부하며, validated에는 contribution=eligible도 요구합니다. contributed로 가려면 이전 기록도 참여 자격을 갖고 있어야 합니다. 단순히 프로세스가 종료됐다는 이유로 성공적인 기여가 되지는 않습니다.

결과 사용 여부는 run_contract_contribution_eligible()로 따로 판단합니다. 정상 기여 외에 degraded이면서 eligible-with-warning인 경우도 허용할 수 있습니다. 따라서 “경고 있음”과 “사용 불가”도 같은 상태가 아닙니다.

갱신에는 잠금을 사용하며, 원장과 스냅샷의 일치 여부를 확인하고 필요하면 되돌리거나 다시 만듭니다. 작은 파일 시스템 위에 트랜잭션과 비슷한 문제를 직접 해결한 사례입니다. 데이터베이스 수준의 모든 내구성 보장을 제공한다고 확대해서 읽을 필요는 없습니다.

프로세스가 끝났다는 사실, 출력이 있다는 사실, 결과를 종합에 쓸 수 있다는 판단을 각각 분리해야 자동화의 실패가 드러납니다.

4-5. 설계 패턴 ④ 병렬 분산·종합과 작업 공간 격리

scripts/lib/parallel.sh의 fan_out()은 같은 요청을 여러 제공자에게 분배합니다. aggregate_results()는 결과를 모으고 품질 신호로 정렬합니다. 결과가 둘 이상이고 종합 실행기를 사용할 수 있으며 모의 실행이 아닐 때 모델 종합을 시도하고, 조건이 맞지 않거나 모델 종합에 실패하면 단순 결합 결과를 남깁니다. 종합 요청에는 겹치는 내용을 합치되 짧은 소수 의견과 충돌도 보존하라는 지침이 들어 있습니다.

구현 단계는 동시에 파일을 고치는 문제가 추가됩니다. tangle_develop()은 기본적으로 tangle_prepare_run_worktree()에서 원본 HEAD 커밋을 기준으로 octopus/run/실행ID/integration 브랜치와 별도 worktree를 만듭니다. 원본 작업 경로의 미커밋 변경을 차단하는 검사는 OCTOPUS_TANGLE_REQUIRE_CLEAN_BASELINE=true로 켜는 선택 사항입니다. PROJECT_ROOT를 그 경로로 바꿔 실행한 뒤 원래 위치로 복원합니다.

# tangle_prepare_run_worktree()의 실제 생성 명령
git -C "$source_root" worktree add -b "$TANGLE_RUN_BRANCH" \
  "$TANGLE_RUN_WORKTREE" "$source_commit"

완료하거나 실패한 뒤에도 이 실행용 브랜치와 worktree를 검토용으로 보존하는 코드가 있습니다. worktree는 충돌을 줄이는 작업 경로 분리이며 별도의 저장소 전체 복사나 운영체제 보안 샌드박스와 같은 개념은 아닙니다.

프로세스에도 경계가 필요합니다. shared/process_supervisor.py의 run_bounded_process()는 OpenAI 호환 에이전트 보조 도구와 라우팅 미리보기에서 사용됩니다. POSIX에서는 새 세션을 만들고, 시간 초과 시 그룹에 SIGTERM을 보낸 뒤 유예 시간이 지나면 SIGKILL을 보냅니다. 출력 제한과 자식이 파이프를 계속 잡는 상황도 다룹니다.

모든 호출이 이 Python 함수를 통과하는 것은 아닙니다. 셸 제공자 실행에는 별도의 시간 제한 경로가 있으며, scripts/lib/agent-sync.sh는 제한 시간을 강제할 수 없는 호스트 팀 실행 대신 감독 가능한 하위 프로세스를 고르는 조건도 둡니다.

4-6. “75% 합의”를 실제 판정식으로 읽기

scripts/lib/testing.sh의 validate_tangle_results()는 최신 결과 상태가 성공이고 차단 사유가 없는 하위 작업을 셉니다. 기본 성공률은 다음 정수 계산에서 시작합니다.

# validate_tangle_results()에서 발췌
local total=$((success_count + fail_count))
local success_rate=0
[[ $total -gt 0 ]] && success_rate=$((success_count * 100 / total))

4개 중 3개가 성공하면 75%입니다. 이것은 “답변이 맞을 확률 75%”가 아닙니다. 수정 결과가 적용된 뒤 유효 성공률을 다시 계산하는 경로가 있고, 명시한 파일의 누락이나 구현 요청인데 변경이 없는 경우 같은 별도 조건이 통과를 막을 수 있습니다.

scripts/lib/quality.sh의 기본 단계 임계치는 조사 50, 정의 75, 구현 75, 전달 80, 보안 100입니다. get_gate_threshold()는 보안 설정을 100 아래로 낮추려 하면 100으로 올립니다. 임계치 100 역시 무결점 보안의 증명이 아니라 해당 절차의 통과 기준입니다.

Council은 또 다릅니다. 응답·최종 판정·독립 승인 계열·근거 상태를 집계하고, council_scan_veto_artifacts()는 거부권을 가진 페르소나의 중대 위험 선언을 찾습니다. 정족수를 통과해도 의장 종합이 없으면 chair_synthesis_available로 별도 표시합니다. 하나의 퍼센트만으로 이 모든 판단을 설명할 수 없습니다.

5디렉토리 구조 해부

위 트리는 핵심 경로를 고른 요약입니다. Markdown 파일이 많지만 모두 일반 설명서는 아닙니다. commands/embrace.md처럼 호스트가 따라야 할 절차와 실행 명령을 담은 문서도 있고, agents/personas/처럼 모델에 주입하는 역할 지침도 있습니다.

5-1. “명령 → 함수 → 결과 파일” 순서로 읽기

처음부터 모든 파일을 정독할 필요는 없습니다. scripts/orchestrate.sh는 3,386줄이고 scripts/lib/workflows.sh는 6,941줄입니다. 이름 검색으로 진입 함수를 찾고 그 함수가 읽는 파일과 호출하는 함수를 따라가는 편이 이해하기 쉽습니다.

5-2. 생성된 파일의 소유권도 아키텍처다

.claude-plugin/marketplace.json은 scripts/sync-marketplace.sh가 생성하고, scripts/sync-readme.py는 README들과 PRODUCT.md의 현재 정보 동기화를 담당합니다. 수정할 대상이 원본인지 생성물인지 구분하지 않으면 다음 동기화 때 변경이 사라집니다.

6학습 포인트 (기술별)

6-1. Bash: 문자열을 데이터로 안전하게 전달하기

scripts/lib/command-argv.sh는 따옴표와 공백을 인자 배열로 바꾸고, scripts/lib/dispatch-plan.sh는 배열을 JSON으로 직렬화합니다. 셸의 문자열은 공백 분리·와일드카드 확장·명령 치환을 만날 수 있으므로 “잘 출력된다”만으로 안전한 전달이 검증되지는 않습니다.

# 인자 경계를 보존하는 기본 형태를 익히는 학습용 예시
args=("첫 번째 인자" "공백 있는 파일.md" "별표 * 를 포함한 문장")
printf '[%s]\n' "${args[@]}"

배울 것: "${args[@]}", 종료 코드, 파이프라인 실패, 표준 출력과 표준 오류 분리입니다. 작은 연습: 공백·따옴표·별표가 들어간 입력 다섯 개를 적고, 배열과 하나의 문자열로 전달할 때 인자 개수가 어떻게 달라질지 예상해 보세요.

scripts/lib/utils.sh의 json_extract_multi()는 Bash 4.3의 nameref 대신 printf -v를 씁니다. 최신 문법을 아는 것과 지원할 환경에서 동작하는 문법을 고르는 것은 다른 능력입니다.

6-2. TypeScript: 실행 경계를 주입해서 검사하기

runOrchestrate()는 마지막 인자로 실행 함수 executor를 받으며 기본값은 비동기 execFile입니다. 테스트에서는 이를 가짜 함수로 바꿔 실제 AI나 셸을 호출하지 않고도 명령 인자·현재 디렉터리·환경변수를 관찰할 수 있습니다.

tests/unit/test-mcp-server.sh에는 서로 다른 두 프로젝트 호출을 함께 만들고, 각 호출의 cwd와 OCTOPUS_PROJECT_DIR가 섞이지 않는지 확인하는 사례가 있습니다. 이는 함수 내부 코드 모양보다 “각 요청이 자기 프로젝트에 묶인다”는 동작 계약을 검사합니다.

작은 연습: 실행 함수가 받은 파일명·인자·작업 경로를 배열에 저장하게 설계하세요. 반환값을 성공·예외로 바꾸면서 호출자가 오류를 어떻게 표시해야 하는지 표로 정리하면 좋습니다.

6-3. Python: 부모 프로세스보다 넓은 생명주기 보기

어떤 CLI는 다시 셸이나 다른 실행기를 띄웁니다. 부모만 종료하면 자식이 남아 비용을 쓰거나 출력 파이프를 계속 잡을 수 있습니다. shared/process_supervisor.py는 start_new_session, os.killpg(), time.monotonic()을 사용해 시간과 프로세스 그룹을 함께 다룹니다.

배울 것: 벽시계와 단조 시계의 차이, 정상 종료 요청과 강제 종료의 차이, 출력 상한의 필요성입니다. 작은 연습: “부모 종료·자식 생존·파이프 열림” 상황을 종이에 그려 보고 누가 어떤 자원을 닫아야 하는지 표시하세요.

6-4. Git: 브랜치와 worktree를 따로 이해하기

브랜치는 커밋을 가리키는 이름이고 worktree는 파일을 실제로 펼쳐 놓은 작업 경로입니다. tangle_prepare_run_worktree()는 두 가지를 함께 만듭니다. 기준 커밋을 고정해야 나중에 “이번 실행이 무엇을 바꿨는가?”를 비교할 수 있습니다.

작은 연습: 원본 경로·기준 SHA·실행 브랜치·실행 경로를 네 칸으로 나누고 같은 실행을 표현해 보세요. 실행 실패 후에도 브랜치를 남기는 이유를 복구와 검토 관점에서 설명하면 이해한 것입니다.

6-5. JSONL: 기록과 현재 상태를 분리하기

scripts/lib/run-contract.sh는 JSONL 기록을 참여자 ID별로 모아 최신 상태를 만듭니다. 현재 상태만 덮어쓰면 “왜 실패했는가?”의 순서가 사라집니다. 반대로 이력만 있으면 현재 상태를 찾는 비용이 커집니다. 원장과 스냅샷은 서로 다른 질문에 답합니다.

작은 연습: 한 참여자의 상태가 세 번 바뀌고 다른 참여자가 두 번 바뀐 다섯 줄짜리 기록을 만드세요. ID별 마지막 줄만 선택하는 로직을 직접 작성하고 입력 순서를 바꾸면 무엇이 달라지는지 살펴보세요.

6-6. 보안: 권한·데이터·기억의 경계를 구분하기

shared/adapter-runtime.mjs의 providerEnvironment()는 허용된 제공자 환경변수 이름을 골라 전달합니다. MCP 쪽에서는 일부 Octopus 설정 접두어도 전달하되 샌드박스·자율성 등에 관한 네 변수는 별도 차단합니다. 제공자 자격증명 목록과 전체 환경을 그대로 복사하는 동작은 다릅니다.

scripts/lib/validation.sh의 wrap_untrusted_content()는 외부 문서를 신뢰할 수 없는 분석 대상으로 표시합니다. 이 표식은 모델에게 주는 지침이지, 운영체제 권한을 제한하는 기술은 아닙니다. 모델 지침, 파일 경로 검증, 실제 실행 권한은 각각 확인해야 합니다.

# 공용 경로 함수의 핵심 부분 발췌
local project="${CLAUDE_PROJECT_DIR:-$PWD}"
local config_root="${CLAUDE_CONFIG_DIR:-${HOME}/.claude}"
encoded="${project//[^a-zA-Z0-9]/-}"
memory_dir="$config_root/projects/$encoded/memory"

6-7. Markdown: 선언과 강제를 구분하기

commands/embrace.md와 스킬 파일은 실행 순서를 명령형 문장으로 강하게 지시합니다. 그러나 문서가 “반드시”라고 적었다고 셸 함수에 같은 방어 조건이 자동으로 생기지는 않습니다. 단계별 결과 파일의 존재를 검사하는 코드처럼 실제 경계에서 강제하는 장치도 함께 찾아야 합니다.

작은 연습: 지침에서 규칙 하나를 골라 “누가 읽는가, 어디서 강제되는가, 실패 기록은 어디에 남는가” 세 질문에 답하세요. 강제 지점을 찾지 못하면 문서상의 약속이라고 표시하면 됩니다.

기술을 배운다는 것은 문법을 외우는 데서 끝나지 않고, 경계가 어긋나는 실패 상황을 설명할 수 있게 되는 것입니다.

7하드웨어 / 시스템 요구사항

7-1. 저장소에서 확인되는 시스템 조건

네이티브 Windows 환경에서는 세션 훅 초반에 MINGW*·MSYS*·CYGWIN*를 확인하고 종료하는 코드가 있습니다. 공용 Python 코드에 Windows용 분기가 있다는 사실만으로 플러그인 전체의 네이티브 Windows 지원을 추론할 수는 없습니다.

7-2. CPU·메모리·GPU는 어느 정도 필요한가?

저장소에 CPU 코어 수, 최소 RAM, 디스크 용량의 통일된 공식 수치는 없습니다. 따라서 “최소 8GB면 모든 작업 가능” 같은 수치를 요구사항으로 제시할 근거는 없습니다. 소스 읽기와 가짜 응답으로 하는 실습에는 모델 가중치를 올릴 필요가 없습니다.

scripts/lib/quality.sh의 기본 동시 실행 수는 MAX_PARALLEL=3입니다. 이 값은 하드웨어 요구사항이나 모든 워크플로의 실제 참여자 수를 뜻하지 않습니다. 다른 흐름은 별도의 구성과 실행 경로를 사용합니다.

7-3. 시간을 제한하는 계층도 여러 개다

긴 작업이 중간에 끊기면 모델 품질부터 의심하기보다 바깥 호출자, 단계, 개별 제공자 중 어느 시간 제한에 걸렸는지 구분해야 합니다. 숫자 하나를 늘려도 다른 계층이 먼저 중단할 수 있습니다.

필요한 장비를 판단할 때는 Octopus 자체보다, 동시에 실행할 제공자와 대상 프로젝트의 빌드·추론 부담을 먼저 보아야 합니다.

8직접 해볼 수 있는 실습 과제

아래 다섯 과제는 저장소를 읽거나 별도의 작은 학습 예제를 만드는 방식입니다. 실제 제공자 호출, 인증키, 자동 구현은 필요하지 않습니다. 각 과제의 통과 기준은 결과물이 무엇을 설명해야 하는지에 맞췄습니다.

rg -n 'octopus_develop|runOrchestrate' mcp-server/src/index.ts
rg -n 'tangle_develop|tangle\)' scripts/orchestrate.sh
rg -n '^tangle_develop\(\)|^tangle_prepare_run_worktree\(\)' scripts/lib/workflows.sh

allowed = {
    (None, "planned"),
    ("planned", "starting"),
    ("starting", "authenticated"),
    ("authenticated", "running"),
    ("running", "output_received"),
    ("output_received", "validated"),
    ("validated", "contributed"),
    ("running", "failed"),
}

def can_move(before, after):
    return (before, after) in allowed

assert can_move("planned", "starting")
assert not can_move("planned", "contributed")
assert not can_move("contributed", "running")

// 네트워크나 프로세스 실행 없이 관찰하는 학습용 예시
type Call = { file: string; args: string[]; cwd: string };
const calls: Call[] = [];

async function recordExecution(call: Call) {
  calls.push({ ...call, args: [...call.args] });
  return { stdout: call.cwd, stderr: "" };
}

await Promise.all([
  recordExecution({ file: "가짜실행기", args: ["probe", "질문 A"], cwd: "/example/a" }),
  recordExecution({ file: "가짜실행기", args: ["ink", "질문 B"], cwd: "/example/b" }),
]);

responses = [
    {"id": "A", "family": "alpha", "status": "contributed", "verdict": "APPROVE"},
    {"id": "B", "family": "alpha", "status": "contributed", "verdict": "REVISE"},
    {"id": "C", "family": "beta",  "status": "timeout", "verdict": None},
]

좋은 실습 결과는 정상 응답을 멋지게 합치는 것뿐 아니라, 빠진 응답과 충돌한 의견을 독자가 알아볼 수 있게 남기는 것입니다.

9관련 기술 심화 학습 로드맵

한꺼번에 전체 플러그인을 복제하려 하면 제공자 인증과 호스트별 차이부터 만나게 됩니다. 먼저 외부 호출 없는 작은 실행기를 만들고, 매주 실패 상황 하나를 추가하는 편이 설계를 이해하기 쉽습니다.

표의 경로는 저장소 루트 기준입니다. 셸 라이브러리는 scripts/lib/, 테스트는 tests/unit/, 공용 어댑터·프로세스 코드는 shared/에 있습니다. 소스의 정상 경로를 이해한 뒤 관련 테스트에서 실패 사례를 읽는 순서를 권합니다.

9-1. 매주 반복할 세 가지 질문

1. 입력: 어디까지가 믿을 수 있는 설정이고 어디부터가 외부 데이터인가?
2. 종료: 성공·실패·취소를 누가 확정하고 자식 프로세스는 누가 정리하는가?
3. 근거: 다음 단계가 이전 단계의 어떤 파일과 상태를 근거로 삼는가?

9-2. 관심사에 따른 다음 갈림길

작은 실행기에 상태·격리·검증을 한 겹씩 더하면, 이 저장소의 큰 구조도 익숙한 문제들의 조합으로 읽히기 시작합니다.

10핵심 키워드 사전

특히 제공자·모델·페르소나·seat를 구분하세요. 하나의 제공자가 여러 모델로 연결될 수 있고, 같은 모델이 여러 페르소나와 실행 단위로 참여할 수 있습니다. 그 개수들을 같은 의미로 세면 독립적인 검토가 얼마나 이루어졌는지 잘못 판단하게 됩니다.

11참고 링크

11-1. 공식 저장소와 프로젝트 문서

• 공식 저장소 — 프로젝트 소개·공개 이슈·릴리스 입구
• README · 커밋 286ef4d — 기본 사용 흐름과 문서상의 약속
• 아키텍처 문서 — 전체 구성과 책임을 읽는 보조 지도
• 제공자 문서 — 연결·인증·가용성·제공자별 제약
• Council 문서 — 역할 기반 심의·예산·구현 전달
• 개인정보 문서 · 보안 정책 — 데이터와 보안 관련 설명
• v11.15.0 릴리스 · 변경 이력

11-2. 본문에서 특히 중요한 소스

• scripts/orchestrate.sh · scripts/lib/workflows.sh — 진입점과 단계 연결
• mcp-server/src/index.ts · MCP 의존성 — 도구 스키마·실행 함수·버전
• provider-registry.sh · dispatch-plan.sh — 정체성과 실행 결정
• run-contract.sh · 실행 계약 테스트 — 이력·상태·참여 자격
• testing.sh · quality.sh — 성공률 계산과 추가 통과 조건
• council.sh — 정족수·이견·인용 검증·거부권
• shared/process_supervisor.py — 시간·출력·프로세스 그룹 경계
• 세션 자동 메모리 경로 테스트 · 최근 커밋 — 경로 혼동을 막는 회귀 사례
• CI 테스트 구성 · Makefile — 이식성과 생성물 검사를 포함한 품질 관리

11-3. 관련 기술의 공식 학습 자료

• Bash 공식 설명서 — 배열·확장·리다이렉션·작업 제어
• jq 공식 설명서 — JSON 변환·검증·집계
• Git worktree 공식 문서 — 작업 경로와 브랜치의 관계
• Node.js 하위 프로세스 문서 — 실행 파일·인자·작업 경로 전달
• TypeScript 공식 문서 · Zod 공식 문서 — 타입과 런타임 입력 검증
• Python subprocess 공식 문서 · signal 공식 문서 — 프로세스 실행과 종료 신호
• MCP 공식 입문 문서 · MCP TypeScript SDK — 도구 연결의 표준과 구현
• Claude Code 플러그인 문서 — 플러그인 호스트의 기능과 사용 방식

외부 공식 문서는 시간이 지나며 바뀔 수 있습니다. 이 글의 버전·함수 동작 설명은 커밋 286ef4d에 맞추고, 새 기능의 호환성은 사용하는 버전의 문서와 함께 확인하세요.

현재 상태 (2026-10-23 확인)