OpenSpec 모드

OpenSpec 모드는 Claude Code와 Codex 위의 Chorus 플러그인을 위한 선택형 작성 스타일입니다. 활성화된 동안에도 AI-DLC 워크플로는 평소와 똑같이 실행되지만, 제안 작성의 모양이 달라집니다. 자유 형식 Markdown을 Chorus에 곧장 입력하는 대신, 에이전트가 openspec CLI로 디스크에 구조화된 파일을 작성하고, 그것들을 제안의 문서 초안으로 미러합니다. 디스크의 파일이 작업 사본이고, Chorus 초안은 검토자가 제안 페이지에서 읽는 충실한 미러입니다.

OpenSpec이 없을 때는 아무것도 바뀌지 않습니다 — 플러그인은 늘 하던 대로 자유 형식 초안을 작성합니다. OpenSpec 모드는 Claude Code와 Codex 플러그인에만 포함되며, 독립 스킬 배포판은 이를 지원하지 않습니다.

언제 활성화되는가

감지는 세션이 시작될 때 한 번 실행됩니다. OpenSpec 모드가 켜지려면 다음 세 가지 신호가 모두 성립해야 합니다.

1. CHORUS_OPENSPEC_MODE가 off로 설정되어 있지 않다 — 명시적 옵트아웃은 항상 우선합니다.
2. 리포지토리 루트에 openspec/ 디렉터리가 존재한다 — “이 리포지토리는 OpenSpec을 쓴다”는 신호로, openspec init이 만듭니다.
3. openspec CLI가 PATH에 있다 — 이 모드는 변경을 스캐폴딩·검증·아카이브하기 위해 CLI가 필요하므로, 디렉터리만으로는 충분하지 않습니다.

셋 다 성립하면, 연결 토스트가 모드가 켜졌다고 알립니다.

Chorus connected at <your Chorus URL> (OpenSpec Enabled)

openspec/ 디렉터리는 있지만 CLI가 없으면, 토스트는 대신 설치 힌트를 표시하고 에이전트는 자유 형식 경로에 머무릅니다.

Chorus connected at <your Chorus URL> (OpenSpec repo detected — install with: npm i -g @fission-ai/openspec)

설치와 초기화

OpenSpec은 Fission AI의 Node CLI입니다. 먼저 전역으로 설치한 뒤, 에이전트가 제안을 작성하는 리포지토리에서 초기화합니다.

npm install -g @fission-ai/openspec
openspec init

openspec init은 openspec/ 작업 디렉터리(changes/, specs/, 설정과 안내 파일)를 만듭니다. 그 후, 감지가 새 신호 두 가지 — openspec/ 디렉터리와 CLI — 를 인식하도록 에이전트 세션을 재시작하세요.

플러그인 자체의 설치는 런타임별로 Claude Code와 Codex 페이지에서 다룹니다.

proposal, develop, yolo에서의 변화

모드가 활성화된 동안, proposal, develop, yolo 스킬은 kebab-case 슬러그로 디스크에 변경을 작성하고, 세 가지 파일 유형을 Chorus 제안의 문서 초안으로 미러합니다.

디스크의 파일	미러되는 문서
openspec/changes/<slug>/proposal.md	PRD
openspec/changes/<slug>/design.md	기술 설계
openspec/changes/<slug>/specs/<capability>/spec.md	명세(역량마다 하나씩)

openspec/changes/<slug>/tasks.md는 미러되지 않습니다. Chorus 작업 초안이 작업의 유일한 진실 원천이므로, OpenSpec 작업 목록은 디스크에 남겨 둡니다.

이후 실행이 변경을 복구할 수 있도록, 제안 설명에는 정확한 한 줄이 실립니다.

OpenSpec change slug: <slug>

미러는 바이트 단위로 충실합니다 — 플러그인은 각 파일의 바이트를 초안으로 흘려보내지, 모델이 내용을 다시 입력하게 하지 않으므로, 로컬 파일과 Chorus 초안이 동일하게 유지됩니다. 이것을 직접 실행하지는 않습니다. 플러그인의 스킬이 네이티브 MCP 클라이언트 chorus mcp call <tool> --arg-file content=<file>로 처리하며, chorus CLI가 PATH에 없을 때만 레거시 chorus-api.sh / chorus-mcp-call.sh 래퍼로 대체합니다. 정확한 계약(그 오류 시 중단 규칙과 승인 후 재동기화)은 여기서 재현하지 않고 권위 있는 출처에 있습니다. docs/OPENSPEC_MODE.md와 플러그인 스킬 public/chorus-plugin/skills/openspec-aware/SKILL.md를 참고하세요.

openspec archive는 언제 실행되는가

openspec archive는 변경의 맨 마지막으로 미뤄집니다. 변경의 마지막 작업이 검증된 후, 플러그인은 에이전트에게 다음을 실행하라고 상기시킵니다.

openspec archive <slug>

아카이브는 변경을 openspec/changes/에서 빼내고, 그 명세 델타를 openspec/specs/ 아래의 장기 명세로 병합합니다. 이어서 플러그인은 갱신된 openspec/specs/<capability>/spec.md 파일을 대응하는 Chorus 문서로 역방향 미러합니다. 그때까지 변경은 진행 중으로 남고 Chorus는 델타 명세만 보게 되므로, 반쯤 병합된 상태를 따질 필요가 없습니다.

옵트아웃

두 스위치, 우선순위 순으로.

1. enableOpenSpec userConfig 토글(Claude Code 플러그인 전용, 기본 켜짐). 플러그인의 설치 구성에서 이를 끄면, 아카이브 리마인더를 포함해 플러그인 전역으로 모드를 비활성화할 수 있습니다. 이는 OpenSpec이 설치되지 않은 것과 동등합니다.

2. CHORUS_OPENSPEC_MODE=off 환경 변수(양쪽 플러그인). 셸 단위로 적용되는, CI 친화적인 옵트아웃입니다. openspec/ 디렉터리와 CLI가 둘 다 있어도 자유 형식 모드를 강제합니다.

   export CHORUS_OPENSPEC_MODE=off

Codex 플러그인에는 userConfig 표면이 없으므로, 거기서는 환경 변수만 적용됩니다. 어느 방법으로 옵트아웃하든, 디스크의 기존 openspec/ 디렉터리는 그대로 남고 새 제안에 슬러그 줄이 붙지도 않습니다. 동작은 OpenSpec이 설치되지 않은 호스트와 완전히 같습니다.

에이전트용

• 트리거. proposal, develop, yolo 스킬은 SessionStart 컨텍스트의 ## OpenSpec Mode 섹션에서 CHORUS_OPENSPEC_ACTIVE를 읽고 그에 따라 분기합니다 — 다시 감지하지 않습니다. CHORUS_OPENSPEC_ACTIVE=1일 때는 디스크에 작성하고 미러하며, 0일 때는 자유 형식 경로를 따릅니다. 변경의 마지막 작업이 검증된 후, PostToolUse 훅이 openspec archive <slug> 리마인더를 주입합니다.
• 제약. 문서 초안 미러 호출은 모두 chorus mcp call <tool> '<json>' --arg-file content=<file> (네이티브 MCP 클라이언트)를 거쳐야 하며, 파일 바이트를 그대로 흘려보내야 합니다. chorus가 PATH에 없을 때만 레거시 chorus-api.sh mcp-tool / chorus-mcp-call.sh 래퍼로 대체합니다. 문서 내용을 인라인으로 다시 입력해서는 절대 안 되며, 어떤 오류가 있으면 중단합니다. tasks.md는 미러하지 마세요. 제안 설명에는 정확한 OpenSpec change slug: <slug> 한 줄을 실어야 합니다. 모드가 꺼져 있을 때는 openspec/changes/를 스캐폴딩하지 말고 슬러그 줄도 추가하지 마세요. 독립 public/skill/ 배포판은 OpenSpec 모드를 지원하지 않습니다.
• 출처. docs/OPENSPEC_MODE.md(사용자 대상 개요와 감지 계약), public/chorus-plugin/skills/openspec-aware/SKILL.md(Claude Code의 권위 있는 스킬), 그리고 plugins/chorus/skills/openspec-aware/SKILL.md(Codex의 권위 있는 스킬).