ClawSpec + OpenSpec 입문: 중단과 수동 개입 없이 프로젝트를 자동적이고 지속적으로 추진하기

난이도: 입문 | 소요 시간: 20분 | 얻는 것: 채팅창에서 OpenSpec으로 프로젝트 전 과정을 관리하고, AI가 멈춤 없이 지속적으로 작업하게 만들기

---

대상 독자

이미 OpenClaw를 실행하여 일상적인 작업을 처리하고 계실 겁니다. 사용 중에 다음과 같은 문제를 겪었을 수 있습니다:

요구사항을 명확히 대화했고 에이전트도 작업을 시작하겠다고 약속했는데, 잠시 후 확인해 보니 진행하지 않고 멈춰서 당신의 재촉을 기다리고 있습니다.

특히 장기 작업, 요구사항 변경, 대화하며 진행하는 시나리오에서 이 문제는 더욱 두드러집니다. 당신에게 필요한 것은 단순히 대화 잘하는 AI가 아니라, 요구사항을 정리하고 지속적으로 추진하며, 사람이 감시하지 않아도 자동으로 복구되는 실행 시스템입니다.

이 글의 대상 독자:

• OpenClaw를 사용 중이며, 채팅 내에서 전체 프로젝트 주기(요구사항 → 기획 → 코드 → 아카이브)를 완료하고 싶은 분
• 에이전트가 작업을 시작한 후 정체된 경험이 있어, 제어 가능한 지속 실행 솔루션을 찾는 분
• OpenSpec 워크플로우에 관심이 있고 이를 OpenClaw에 직접 내장하고 싶은 분

---

핵심 의존성 및 환경

GitHub 저장소: https://github.com/bytegh/clawspec

---

전체 프로젝트 구조

ClawSpec 플러그인 디렉토리 구조(설치 후):

clawspec/
├── index.ts                    # 플러그인 입구
├── src/                       # 핵심 소스 코드
│   ├── service/               # 서비스 레이어
│   ├── watcher/               # 백그라운드 watcher 관리
│   ├── stores/                # 상태 저장소
│   └── hooks/                 # OpenClaw hooks
├── skills/                    # OpenSpec skill 텍스트(내장)
├── test/                      # 테스트 케이스
├── openclaw.plugin.json       # 플러그인 설정
├── package.json
└── tsconfig.json

실행 시 각 repo 아래에 OpenClaw 관리 파일이 생성됩니다:

<repo>/
├── .openclaw/clawspec/        # ClawSpec 런타임 상태
│   ├── state.json             # 현재 프로젝트 상태
│   ├── execution-control.json # cs-work 실행 제어
│   ├── execution-result.json  # 실행 결과
│   ├── worker-progress.jsonl  # 백그라운드 진행 로그
│   ├── planning-journal.jsonl  # 요구사항 논의 기록
│   ├── planning-journal.snapshot.json  # journal 스냅샷
│   ├── rollback-manifest.json # 롤백 리스트
│   ├── snapshots/             # change 스냅샷 기준선
│   │   └── <change-name>/
│   │       └── baseline/
│   └── archives/              # 아카이브된 change
├── openspec/                  # OpenSpec 규격 디렉토리
│   └── changes/<change-name>/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/

---

단계별 가이드

Step 1: ClawSpec 플러그인 설치

ClawSpec은 세 가지 설치 방식을 제공하며, 첫 번째 방식을 권장합니다:

방법 A: OpenClaw 플러그인 설치 관리자 이용(권장)

openclaw plugins install clawspec@latest

방법 B: ClawHub CLI 이용

npx clawhub@latest install clawspec

방법 C: npm 패키지 수동 설치(최후의 수단)

$pkg = npm pack clawspec@latest
openclaw plugins install $pkg

@latest는 항상 npm에 배포된 최신 ClawSpec 버전을 가리킵니다. 아직 npm에 배포되지 않은 개발 중인 커밋을 설치하려면 로컬 체크아웃이나 다운로드한 .tgz 패키지를 사용하세요.

---

Step 2: OpenClaw 설정

설치 완료 후, ~/.openclaw/openclaw.json에서 ACP를 활성화하고 ClawSpec을 설정해야 합니다:

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "claude"
  },
  "plugins": {
    "entries": {
      "clawspec": {
        "enabled": true,
        "config": {
          "defaultWorkspace": "~/clawspec/workspace",
          "openSpecTimeoutMs": 120000,
          "watcherPollIntervalMs": 4000
        }
      }
    }
  }
}

주요 설정 항목 설명:

OpenClaw에 ACPX가 내장되어 있지 않은 경우, ClawSpec이 플러그인 로컬 복사본을 자동으로 설치하므로 수동으로 처리할 필요가 없습니다. ACPX의 명령 경로는 ClawSpec이 직접 관리하므로 별도의 설정이 필요하지 않습니다.

설정 완료 후 게이트웨이를 재시작하세요:

openclaw gateway restart
openclaw gateway status

---

Step 3: workspace와 프로젝트 연결

ClawSpec은 채팅 채널(chat channel)별로 workspace를 기억하며, 각 채널에 서로 다른 프로젝트 루트 디렉토리를 바인딩할 수 있습니다.

/clawspec workspace "D:\clawspec\workspace"
/clawspec use "demo-app"

예상 결과:

• ClawSpec이 현재 채팅 채널에 workspace 경로를 기록합니다.
• demo-app 디렉토리가 없으면 자동으로 생성됩니다.
• 이 repo를 처음 선택할 때 openspec init이 자동으로 실행됩니다.

---

Step 4: OpenSpec change 생성 및 프로젝트 컨텍스트 진입

/clawspec proposal add-login-flow "Build login and session handling"

이 명령은 세 가지 작업을 수행합니다:

1. openspec/changes/add-login-flow/ 아래에 표준 스캐폴딩(proposal.md, design.md, tasks.md, specs/)을 생성합니다.
2. ClawSpec이 현재 추적 중인 파일의 스냅샷 기준선을 만듭니다(추후 rollback용).
3. 현재 채팅이 add-login-flow라는 활성(active) change 컨텍스트로 진입합니다.

이후 모든 채팅 내용은 attached 상태인 한 자동으로 planning journal에 기록됩니다.

---

Step 5: 채팅에서 요구사항 설명

채팅창에서 평소처럼 요구사항을 설명하세요. 예를 들어:

이메일과 비밀번호 로그인을 지원해줘.
refresh token이 필요해.
access token은 15분 후에 만료되게 해줘.

ClawSpec은 이 내용들을 planning-journal.jsonl에 자동으로 추가합니다. 이 시점에서는 아티팩트(artifacts)를 즉시 갱신하거나 코드를 작성하기 시작하지 않습니다. 이 단계는 기록만 할 뿐 행동하지 않습니다.

백그라운드에서 계속 실행되게 두고 현재 창에서는 다른 대화를 하고 싶다면 다음을 사용하세요:

cs-detach

이렇게 하면 일반 대화가 planning journal에서 분리되지만, watcher의 진행 상황 푸시는 계속됩니다. 나중에 다시 연결하려면 다음을 사용하세요:

cs-attach

---

Step 6: cs-plan, 가시적 기획 동기화

요구사항 대화가 충분히 이루어졌다고 판단되면 다음을 실행하세요:

cs-plan

ClawSpec은 현재 보이는 채팅 회차에서 다음 아티팩트들을 직접 갱신합니다:

• proposal.md — 프로젝트 제안서
• design.md — 아키텍처 설계
• specs/ — 상세 규격
• tasks.md — 작업 목록

cs-plan은 백그라운드 ACP worker를 거치지 않고 숨겨진 subagent에 의존하지 않습니다. 메인 채팅창에서 AI가 아티팩트를 갱신하는 과정을 직접 볼 수 있습니다.

---

Step 7: cs-work, 백그라운드 지속 구현 시작

Planning 갱신이 깨끗하게 완료되면 백그라운드 구현을 시작합니다:

cs-work

cs-work는 메인 채팅창에서 직접 코드를 쓰지 않고 다음과 같은 경로를 거칩니다:

1. Planning 상태의 청결도를 검증합니다(dirty journal은 차단됨).
2. execution-control.json에 기록하여 watcher를 활성화합니다.
3. watcher가 acpx를 통해 ACP worker 세션을 시작합니다.
4. worker가 tasks.md에 따라 작업을 하나씩 실행하며 진행 상황을 업데이트하고 worker-progress.jsonl에 기록합니다.
5. watcher가 worker의 진행 이벤트를 짧은 채팅 메시지로 변환하여 사용자에게 푸시합니다.

채팅창에 다음과 같은 메시지들이 차례로 도착할 것입니다:

[Watcher] ACP worker connected...
[Worker] Preparing login-flow: loading context
[Worker] Loaded proposal.md
[Worker] Context ready for Task 1
[Worker] Task 1/5 complete: 사용자 인증 모듈
[Worker] Task 2/5 complete: 토큰 갱신 로직
...
[Worker] All tasks complete.

---

Step 8: 진행 추적 및 복구

이것은 ClawSpec의 핵심 능력 중 하나인 게이트웨이 재시작 후 worker 자동 연결입니다.

게이트웨이가 재시작될 때 watcher manager는 다음을 수행합니다:

• 모든 활성 프로젝트를 스캔합니다.
• 아직 살아있는 ACP worker 세션 탈취를 우선적으로 시도합니다.
• 이전 worker가 죽었다면 자동으로 다시 무장(arm)하고 대체 worker를 시작합니다.
• 작업 진행 상황과 worker progress offset을 유지합니다.

즉, 게이트웨이 재시작 후 수동으로 cs-work를 재촉할 필요가 없습니다. ClawSpec이 자동으로 끊긴 작업을 다시 연결합니다.

실행 중 worker 상태 확인:

/clawspec worker status

다음을 표시합니다:

• 현재 설정된 worker 에이전트
• 전송 계층 상태(connected / disconnected)
• Startup phase(loading context / ready / running)
• 실시간 pid, heartbeat, 다음 단계 제안

ACP worker 실패 시 ClawSpec은 "복구 가능한 오류"와 "실제 차단 요인(blocker)"을 구분하며, 복구 가능한 오류에 대해 백오프를 포함한 제한된 횟수의 재시도를 수행합니다. 재시도 한도(기본 10회)를 초과하면 프로젝트는 blocked로 표시되며 수동 개입이 필요합니다.

협업적 일시 중지 및 재개:

cs-pause        # worker를 안전한 경계에서 일시 중지
cs-continue     # 기획 또는 구현 재개

---

Step 9: 아카이브 및 마무리

모든 작업이 완료되면 활성 change를 정리합니다:

/clawspec archive

이 작업은 다음을 수행합니다:

1. OpenSpec change의 무결성을 검증합니다.
2. 완료된 change를 archives/ 디렉토리로 이동시킵니다.
3. 현재 채팅의 active change 상태를 삭제합니다.
4. (코드 변경 사항을 유지하지 않고) 현재 change를 포기하고 싶다면:

/clawspec cancel

ClawSpec은 전체 저장소 레벨의 git reset --hard 대신 스냅샷 기준선에서 추적 중인 파일만 복구합니다.

전체 작업 사이클은 다음과 같습니다:

요구사항 대화 → cs-plan → cs-work → 진행 대기 → cs-detach(선택 사항) → cs-attach(선택 사항)
→ /clawspec archive(완료 후)

---

자주 발생하는 문제 해결

1. cs-work 시 "planning sync가 먼저 필요합니다"라는 메시지가 뜨는 경우

원인:

• planning journal이 dirty 상태가 됨(스냅샷 이후 새 요구사항 대화 발생)
• planning 아티팩트가 누락되었거나 만료됨
• OpenSpec apply state가 여전히 blocked 상태임

처리 방법:

cs-plan
# planning 완료 대기
cs-work

---

2. Watcher에서 ACPX를 사용할 수 없다는 메시지가 뜨는 경우

원인은 다음과 같을 수 있습니다:

• acp.enabled가 활성화되지 않음
• acp.backend가 acpx가 아님
• acp.defaultAgent가 설정되지 않음
• OpenClaw에 ACPX가 내장되어 있지 않고, ClawSpec도 사용 가능한 복사본을 찾지 못함

빠른 수정:

openclaw config set acp.backend acpx
openclaw config set acp.defaultAgent claude
openclaw gateway restart
cs-work

ACPX를 여전히 사용할 수 없는 경우 ClawSpec이 자동으로 플러그인 로컬 복사본 설치를 시도합니다. 첫 설치 시에는 약간의 시간과 네트워크 연결이 필요할 수 있습니다.

---

3. 일반 대화가 planning journal을 오염시킨 경우

일반적인 대화가 journal에 기록되어 나중에 cs-work가 dirty 상태로 차단되는 경우입니다.

즉시 분리:

cs-detach

나중에 다시 요구사항을 논의하고 싶을 때:

cs-attach

---

4. Worker가 연결되었지만 작업을 시작하지 않는 경우

보통 ACP worker가 활성화되었지만 implementation prompt를 소화하거나 planning 아티팩트를 읽고 있는 상태입니다.

다음 두 종류의 메시지를 우선 확인하세요:

• Watcher 측 상태: "starting worker", "ACP worker connected..."
• Worker가 출력하는 로딩 상태: "Preparing <task>: loading context", "Loaded proposal.md", "Context ready..."

"Context ready for ..."가 보인다면 worker가 아티팩트를 다 읽었으며 곧 첫 번째 작업을 시작한다는 의미입니다.

/clawspec worker status를 실행하여 startup phase와 startup wait 필드를 중점적으로 보고 worker가 현재 어느 단계에서 멈춰 있는지 판단하세요.

---

5. Worker 오류 "stdin is not a terminal" 또는 세션 생성 결과가 없는 경우

원인:

• ~/.acpx/config.json에 사용자 정의 에이전트 설정이 존재함(예: agents.codex가 로컬 CLI 경로를 가리킴)
• acpx가 비대화형 환경에서 raw CLI 방식으로 에이전트를 시작할 수 없음

진단 실행:

/clawspec doctor

사용자 정의 에이전트 설정 문제가 보고되면 자동 수정을 실행하세요:

/clawspec doctor fix

수동 수정: ~/.acpx/config.json을 편집하여 "agents"를 빈 객체로 설정합니다:

{
  "agents": {}
}

---

6. /clawspec use 실행 시 이미 완료되지 않은 change가 있다는 메시지가 뜨는 경우

이는 예상된 동작입니다. ClawSpec은 동일한 repo에서 활성 change를 남겨둔 채 다른 작업을 하는 것을 허용하지 않습니다.

세 가지 중 하나를 선택하세요:

/clawspec continue      # 현재 change 계속하기
/clawspec archive       # 완료된 change 아카이브하기
/clawspec cancel        # 현재 change 포기하기

---

추가 읽을거리 / 심화 방향

1. OpenSpec CLI 고급 사용법

ClawSpec에 내장된 OpenSpec CLI 자체는 완전한 프로젝트 규격 관리 시스템입니다. 프로젝트 디렉토리에서 직접 실행할 수 있습니다:

openspec status        # 현재 change 상태 확인
openspec diff          # 현재 파일과 스냅샷 기준선 비교
openspec validate      # OpenSpec 규격 무결성 검증

OpenSpec의 propose → design → spec → task → apply 체인을 깊이 이해하면 change의 입도와 범위를 더 잘 계획할 수 있습니다.

2. ClawSpec 다중 채널 다중 프로젝트 병렬 관리

ClawSpec의 workspace는 채널별로 기억되므로 다음과 같은 작업이 가능합니다:

• Telegram 채널에서는 백엔드 API 프로젝트 관리
• Discord 채널에서는 프런트엔드 프로젝트 관리
• 동일한 repo라도 채널마다 다른 활성 change를 가질 수 있음 (단, 동일 repo 전체에서는 글로벌하게 하나의 미완료 change만 허용됨)

cs-detach를 적절히 사용하여 각 채널을 계속 주시하지 않고도 백그라운드 작업이 계속 돌아가게 하세요.

3. ACP worker 사용자 정의 에이전트 설정

글로벌 acp.defaultAgent 외에도 특정 채널/프로젝트를 위해 worker 에이전트를 전환할 수 있습니다:

/clawspec worker codex    # 현재 채널/프로젝트에 codex 사용
/clawspec worker claude  # claude로 다시 전환

여러 에이전트 설정(예: 능력치별 모델)이 있는 경우, 이 기능을 통해 작업의 복잡도에 따라 적합한 worker를 선택할 수 있습니다.

4. OpenSpec의 다른 도구 체인과 협업

ClawSpec이 출력한 tasks.md와 proposal.md는 다른 도구(예: Superpowers, 사용자 정의 CI 스크립트)에서 읽어 더 완벽한 프로젝트 관리 루프를 형성할 수 있습니다. OpenSpec의 규격 파일은 순수 Markdown이며 형식이 개방되어 있어 특정 UI에 종속되지 않습니다.

5. ClawSpec 설정 커스터마이징

plugins.entries.clawspec.config에는 다음과 같은 고급 옵션이 더 있습니다:

{
  "clawspec": {
    "enabled": true,
    "config": {
      "archiveDirName": "archives",
      "allowedChannels": ["ch_xxx", "ch_yyy"]
    }
  }
}

allowedChannels 필드를 사용하면 ClawSpec이 지정된 채널에서만 작동하도록 제한할 수 있어, 팀 내 일부 채널에서 이 워크플로우가 필요하지 않은 경우에 적합합니다.