AI 보조 코딩을 위한 로컬 우선 멀티 에이전트 워크플로우를 구축하고 있습니다

지난 며칠 동안 저는 Codex Engineering Workflow Pack이라는 오픈 소스 프로젝트에 집중하고 있습니다.

GitHub: https://github.com/SetraTheXX/Codex-Engineering-Workflow-Pack
npm: https://www.npmjs.com/package/@setrathex/codex-engineering-workflow-pack

이 프로젝트는 단순한 아이디어에서 시작되었습니다:

Codex가 매번 처음부터 시작하는 대신, 재사용 가능한 엔지니어링 워크플로우 (engineering workflow)를 가지고 있다면 어떨까?

처음에 이 프로젝트는 단순한 스킬 팩 (skill pack)이었습니다. 목표는 Codex에게 다음과 같은 작업들을 위한 구조화된 워크플로우를 제공하는 것이었습니다:

• PRD (제품 요구 사항 문서) 작성
• 이슈 분할 (slicing issues)
• 디버깅 (debugging)
• TDD (테스트 주도 개발)
• 핸드오프 (handoffs)
• 아키텍처 리뷰 (architecture review)
• 코드베이스 분석 (codebase analysis)

그것은 유용했지만, AI 코딩 도구들을 더 진지하게 사용하면서 더 큰 문제를 발견하기 시작했습니다.

워크플로우가 구조화되어 있지 않으면 AI 코딩은 종종 엉망이 됩니다.

모델은 코드를 빠르게 생성할 수 있지만, 그 주변 프로세스는 대개 불분명합니다:

• 정확한 작업 내용이 무엇인가?
• AI가 편집할 수 있는 파일은 어떤 것인가?
• 작업을 어떻게 격리 (isolate)할 것인가?
• 결과물을 어떻게 리뷰 (review)할 것인가?
• 두 에이전트가 겹치는 파일을 편집하면 어떻게 되는가?
• 작업 범위를 벗어난 실수로 인한 변경을 어떻게 방지할 것인가?
• 감사 추적 (audit trail)을 어떻게 유지할 것인가?

이것이 제가 해결하고자 하는 문제입니다.

목표

CEWP를 통한 저의 목표는 단순히 AI가 더 많은 코드를 쓰게 만드는 것이 아닙니다.

목표는 AI 보조 개발 (AI-assisted development)을 더 구조화되고, 감사 가능하며, 실제 엔지니어링 워크플로우에 더 가깝게 만드는 것입니다.

하나의 AI 모델이 무작위로 저장소 (repo)를 편집하는 대신, 저는 다음과 같은 워크플로우를 원합니다:

1. 매니저 (manager) 역할이 작업을 계획합니다.
2. 워커 (worker) 역할이 격리된 작업을 구현합니다.
3. 리뷰어 (reviewer) 역할이 결과물을 확인합니다.
4. 파일 범위 (file scopes)가 강제됩니다.
5. 위험한 경계 (boundaries)가 보호됩니다.
6. 사용자는 중요한 작업을 수행하기 전에 최종 보고서를 받습니다.

다시 말해:

AI는 단순히 "코딩"만 해서는 안 됩니다. 통제된 엔지니어링 시스템 (engineering system) 내부에서 작동해야 합니다.

v0.2에서 CEWP가 된 것

v0.2.0-beta.1과 함께, CEWP는 더 이상 단순한 스킬 팩 (skill pack)이 아닙니다.

이제 cewp CLI를 중심으로 구축된 로컬 우선 (local-first) 워크플로우 런타임 (runtime)을 포함합니다.

현재 포함된 구성 요소 중 일부는 다음과 같습니다:

• Codex 스킬 팩 (skill pack)
• cewp CLI
• 코디네이터 모드 (Coordinator Mode) 런타임 (runtime)
• Git 워크트리 격리 (worktree isolation)
• 작업자 (worker) / 검토자 (reviewer) 역할
• 디스패치 계획 (dispatch planning)
• 보호된 실행 (guarded execution)
• 순차적 및 병렬 작업자 (sequential and parallel workers)
• 검토자 게이트 (reviewer gates)
• 마무리 / 정리 / 가지치기 (finalize / cleanup / prune) 도우미
• 운영자 정책 모드 (operator policy modes)
• 하네스 스모크 테스트 (harness smoke tests)

이 프로젝트는 아직 베타 단계이지만, 이제 프롬프트 파일 (prompt files)의 모음이라기보다 개발자 도구 제품에 훨씬 더 가깝게 동작합니다.

왜 로컬 우선 (local-first)인가?

AI 코딩 워크플로우는 보통 실제 저장소 (repository) 내부에서 발생하기 때문에, CEWP가 로컬 우선 (local-first) 방식이 되기를 원했습니다.

저장소에는 이미 다음과 같은 중요한 컨텍스트 (context)가 포함되어 있습니다:

• 소스 코드 (source code)
• README 파일
• 문서 (docs)
• 로드맵 (roadmap) 파일
• 제품 요구 사양서 (PRDs)
• 이슈 (issues)
• 테스트 (tests)
• 로컬 스크립트 (local scripts)
• Git 히스토리 (Git history)

따라서 CEWP는 런타임 상태 (runtime state)를 저장소 내의 .cewp/ 디렉토리에 저장합니다.

각 실행 (run)은 고유한 폴더를 가집니다:

.cewp/runs/<run-id>/

해당 실행은 다음과 같은 것들을 포함할 수 있습니다:

• 실행 메타데이터 (run metadata)
• 보드/태스크 상태 (board/task state)
• 프롬프트 (prompts)
• 보고서 (reports)
• 검토 패킷 (review packets)
• 어댑터 출력 (adapter output)
• 이벤트 로그 (event logs)

이를 통해 워크플로우를 가시화하고 조사할 수 있습니다. 사용자는 AI를 블랙박스 (black box)로 취급하는 대신 무엇이 일어났는지 확인할 수 있습니다.

워크트리 격리 (Worktree isolation)

CEWP의 가장 중요한 부분 중 하나는 Git 워크트리 격리 (Git worktree isolation)입니다.

작업자들이 실행될 때, 모두가 동일한 작업 디렉토리 (working directory)를 수정하지 않습니다.

각 작업자는 자신만의 Git 워크트리 (Git worktree)를 가질 수 있습니다.

이것이 중요한 이유는, 여러 에이전트 (agents)가 동일한 디렉토리 내의 동일한 파일을 수정할 경우 병렬 AI 작업이 매우 빠르게 위험해질 수 있기 때문입니다.

별도의 워크트리를 사용하면 각 작업자는 분리된 작업 공간 (workspace)을 갖게 됩니다. 이는 변경 사항을 조사, 수집 및 검증하는 것을 더 쉽게 만듭니다.

기본적인 아이디어는 다음과 같습니다:

worker-a -> 별도의 워크트리 (separate worktree) -> 작업 A
worker-b -> 별도의 워크트리 (separate worktree) -> 작업 B
reviewer -> 수집된 출력물 검사

이것이 통제된 병렬 작업 (controlled parallel work)을 위한 기초입니다.

병렬 워커 (Parallel workers)

최근 제가 가장 많은 노력을 기울인 부분은 병렬 워커 (parallel worker) 시스템입니다.

아이디어는 간단합니다:

두 작업이 독립적이라면, 두 명의 워커가 동시에 작업할 수 있어야 합니다.

하지만 "병렬 AI 에이전트 (parallel AI agents)"는 시스템이 위험 요소를 먼저 확인하는 경우에만 의미가 있습니다.

병렬 실행에 앞서, CEWP는 다음과 같은 사항들을 확인합니다:

• 워커들이 별도의 워크트리 (worktrees)를 사용하고 있는가?
• 파일 범위 (file scopes)가 서로 겹치는가?
• allowedFiles (허용된 파일)가 정의되었는가?
• forbiddenFiles (금지된 파일)가 준수되고 있는가?
• 출력 경로 (output paths)가 분리되어 있는가?
• 워크트리 경로 (worktree paths)가 안전한가?
• 한 워커가 실수로 다른 워커의 범위를 건드리게 될 것인가?

예를 들어, 다음은 겹치는 것으로 간주되어야 합니다:

docs/**
docs/install.md

docs/install.md가 docs/** 내부에 있기 때문입니다.

이제 CEWP는 이러한 케이스를 감지하고 안전하지 않은 병렬 실행을 차단합니다.

목표는 "모든 것을 한꺼번에 실행하는 것"이 아닙니다.

목표는 다음과 같습니다:

워크플로우가 작업들이 충분히 격리되어 있음을 증명할 수 있을 때만 병렬로 실행합니다.

파일 범위 가드레일 (File scope guardrails)

AI 코딩 도구는 의도한 작업 이외의 파일을 실수로 수정할 수 있습니다.

따라서 CEWP는 작업 수준의 파일 범위 (task-level file scopes)를 사용합니다.

워커 작업은 다음과 같이 정의할 수 있습니다:

{
  "allowedFiles": ["README.md", "docs/install.md"],
  "forbiddenFiles": ["package.json"]
...

v0.2.0-beta.1 버전부터 실제 워커 실행 시에는 명시적이고 비어 있지 않은 allowedFiles가 필요합니다.

이는 워커가 빈 범위로 실행되어 저장소 (repo)를 자유롭게 수정할 수 없음을 의미합니다.

또한 CEWP는 다음 두 가지를 모두 확인합니다:

• 커밋되지 않은 변경 사항 (uncommitted changes)
• 커밋된 브랜치 변경 사항 (committed branch changes)

이 부분은 매우 중요합니다.

한때 자동화된 리뷰를 통해 실제 문제가 지적된 적이 있었습니다. 만약 워커가 반환하기 전에 파일을 커밋해 버리면, git status는 깨끗해 보일 수 있고 범위 확인 (scope check) 과정에서 해당 변경 사항을 놓칠 수 있다는 점이었습니다.

이 문제는 baseCommit을 기록하고 해당 베이스 이후의 커밋된 변경 사항을 확인하는 방식으로 해결되었습니다.

따라서 워커 (worker)는 단순히 변경 사항을 커밋하는 것만으로는 범위 확인 (scope checks)을 우회할 수 없습니다.

리뷰어 게이트 (Reviewer gate)

워크플로우는 워커들이 작업을 마쳤다고 해서 바로 종료되지 않습니다.

CEWP는 워커의 보고서를 수집하여 리뷰 패킷 (review packet)을 생성합니다.

그 후 리뷰어 (reviewer)가 출력을 확인하고 결정을 작성합니다.

finalize를 위해서는 다음이 필요합니다:

Decision: PASS

이는 finalize가 단순히 "워커가 수행한 모든 것이 수락된다"는 의미가 아님을 뜻합니다.

별도의 리뷰 게이트 (review gate)가 존재합니다.

AI가 생성한 변경 사항은 최종 실행 상태 (final run state)가 되기 전에 반드시 검사되어야 하므로, 이 과정은 매우 중요합니다.

운영자 정책 모드 (Operator policy modes)

제가 원했던 또 다른 기능은 권한 모델 (permission model)이었습니다.

어떤 사용자들은 안전하고 단계적인 흐름을 원합니다.

어떤 사용자들은 도구에 더 많은 권한을 부여하기를 원합니다.

개인적으로 저는 작업이 명확하고 저장소 경계 (repository boundaries)가 잘 정의되어 있을 때만 로컬 권한이 많은 AI 코딩 도구를 자주 사용합니다.

따라서 CEWP에는 이제 다음과 같은 정책 모드 (policy modes)가 있습니다:

safe
trusted
full-authority

기본값은 safe입니다.

safe 모드에서는 영향력이 큰 작업들이 차단됩니다.

full-authority 모드에서는 CEWP가 다음과 같은 로컬 워크플로우 작업들을 더 적은 일시 중단과 함께 실행할 수 있습니다:

• 워커 (workers)
• 리뷰어 (reviewer)
• 파이프라인 (pipeline)
• 최종 확정 (finalize)
• 정리 (cleanup)
• 가지치기 삭제 (prune deletion)

하지만 full-authority 모드라고 해서 가드레일 (guardrails)을 비활성화하는 것은 아닙니다.

full-authority 모드에서도 다음 사항들은 여전히 유효합니다:

• allowedFiles (허용된 파일) 설정이 여전히 중요함
• forbiddenFiles (금지된 파일) 설정이 여전히 중요함
• 워크트리 격리 (worktree isolation)가 여전히 중요함
• 리뷰어 게이트 (reviewer gates)가 여전히 중요함
• 대상 워크트리 안전성 (target worktree safety)이 여전히 중요함
• 자동 푸시 (push) / 게시 (publish) / 릴리스 (release)는 발생하지 않음

이러한 차이점은 중요합니다.

full-authority의 의미는 다음과 같습니다:

사용자가 CEWP가 로컬 워크플로우를 실행하는 것을 신뢰한다.

다음과 같은 의미는 아닙니다:

AI가 저장소에 대해 무엇이든 할 수 있다.

v0.2.0-beta.1에서 강화된 사항

0.2.0-beta.1 릴리스는 주로 시스템 강화 (hardening)에 관한 것이었습니다.

주요 개선 사항 중 일부는 다음과 같습니다:

• 런타임 정책 강제 (runtime policy enforcement)
• 실제 워커 실행을 위한 allowedFiles 필수화
• 더 나은 병렬 스코프 중첩 탐지 (parallel scope overlap detection)
• 외부/절대 경로 targetWorktree 차단
• 더 안전한 정리 (cleanup) 동작
• 더 강력한 하네스 테스트 (harness tests)
• 검증을 위한 npm 스크립트
• 더 명확한 문서 및 릴리스 노트

이제 패키지에 다음과 같은 스크립트가 포함되어 있습니다:

npm test
npm run smoke
npm run check
...

하네스 테스트는 다음과 같은 사항들을 다룹니다:

• 정책 게이트 (policy gates)
• 워크트리 (worktree) 생성
• 커밋된 디프 (diff) 가시성
• 허용되지 않은 파일 탐지
• 병렬 중첩 탐지
• 대상 워크트리 정책
• 패키지 표면 검사 (package surface checks)

워크플로우의 모습

단순화된 CEWP 흐름은 다음과 같습니다:

run init
  ↓
worktrees create
...

중요한 것은 명령어 목록이 아닙니다.

중요한 것은 모델입니다:

plan -> isolate -> execute -> collect -> review -> finalize

이것이 제가 AI 코딩 도구들이 따르기를 원하는 워크플로우입니다.

장기적인 비전

현재 CEWP는 Codex에 집중되어 있습니다.

하지만 저는 이 아이디어가 하나의 모델이나 하나의 도구에 국한되기를 원하지 않습니다.

장기적인 비전은 서로 다른 모델이 각기 다른 역할을 맡을 수 있는 어댑터 기반 (adapter-based) 시스템입니다:

• 매니저 (manager)로서의 Codex
• 리뷰어 (reviewer)로서의 Claude
• 워커 (worker)로서의 Gemini
• 워커로서의 OpenCode 또는 API 기반 모델들
• 인간 참여 (human-in-the-loop) 단계를 위한 수동 어댑터

목표는 단순히 많은 모델을 맹목적으로 실행하는 것이 아닙니다.

목표는 각 모델이 적절한 곳에서 사용될 수 있는 역할 기반 (role-based) 워크플로우를 만드는 것입니다.

예를 들어:

manager -> 작업을 계획함
worker-a -> 하나의 스코프를 구현함
worker-b -> 다른 스코프를 구현함
...

이는 제한 사항(limits)과 비용 문제 해결에도 도움이 됩니다. 모든 것이 하나의 모델에 의존하게 되면, 사용량 제한이 병목 현상이 됩니다. 미래의 어댑터 시스템은 CEWP를 더욱 유연하게 만들 수 있습니다.

배운 점

이것을 구축하면서 몇 가지 사실이 명확해졌습니다:

1. AI 코딩에는 경계가 필요하다

코딩 에이전트에게 더 많은 권한을 부여할수록, 스코프 경계 (scope boundaries)는 더욱 중요해집니다.

allowedFiles, forbiddenFiles, worktrees, 그리고 reviewer gates (검토 게이트)는 선택적인 세부 사항이 아닙니다. 이것들은 유용한 워크플로우와 위험한 워크플로우를 가르는 차이점입니다.

2. 병렬성 (Parallelism)은 격리가 동반될 때만 유용합니다

두 개의 에이전트를 동시에 실행하는 것은 인상적으로 들릴 수 있지만, 그들의 작업이 격리 (isolated)되어 있을 때만 유용합니다.

그렇지 않으면, 단지 혼란을 더 빠르게 야기할 뿐입니다.

3. 로컬 우선 (Local-first) 워크플로우는 감사 (audit)하기가 더 쉽습니다

워크플로우가 보고서, 이벤트, 프롬프트 (prompts), 그리고 리뷰 패킷 (review packets)을 로컬에 작성하면, 사용자가 어떤 일이 일어났는지 검사할 수 있습니다.

이는 채팅 기록 (chat history)에만 의존하는 것보다 훨씬 더 낫습니다.

4. "전권 부여 (Full authority)"가 "규칙 없음"을 의미해서는 안 됩니다

일부 사용자들은 정말로 AI에게 더 많은 권한을 부여하기를 원합니다.

그것은 타당합니다.

하지만 시스템은 여전히 엄격한 안전 규칙을 유지해야 합니다. CEWP의 전권 부여 모드는 바로 그 아이디어를 중심으로 설계되었습니다.

현재 상태

CEWP는 아직 베타 버전입니다.

현재 버전은 다음과 같습니다:

0.2.0-beta.1

npm에 게시됨:

npm install @setrathex/codex-engineering-workflow-pack

GitHub:

https://github.com/SetraTheXX/Codex-Engineering-Workflow-Pack

npm:

https://www.npmjs.com/package/@setrathex/codex-engineering-workflow-pack

다음 단계

다음 주요 방향은 v0.3입니다.

제가 탐구하고자 하는 주요 사항은 다음과 같습니다:

• 어댑터 레지스트리 (adapter registry)
• 결정론적 테스트 (deterministic tests)를 위한 가짜 어댑터 (fake adapter)
• 패키지 설치 스모크 테스트 (package install smoke tests)
• CI (지속적 통합)
• 더 나은 운영자 문서 (operator docs)
• 명령 없는 사용 패턴 (commandless usage patterns)
• 향후 Gemini / Claude / OpenCode 어댑터 실험

더 큰 목표는 여전히 동일합니다:

AI 보조 개발을 더 구조화되고, 감사 가능하며, 실제 프로젝트에서 사용할 수 있을 만큼 안전하게 만드는 것.

피드백

저는 특히 다음을 사용하는 분들의 피드백에 관심이 많습니다:

• Codex
• Claude Code
• Cursor
• GitHub Copilot
• Gemini
• OpenCode
• 기타 AI 코딩 도구

제가 고민하고 있는 질문들은 다음과 같습니다:

• AI 워커 (AI workers)를 위한 파일 범위 규칙 (file scope rules)을 어떻게 설계해야 할까요?
• 전체 권한 모드 (full-authority mode)에 커밋 (commit), 푸시 (push), 배포 (publish)가 포함되어야 할까요?
• 모델 독립적인 어댑터 계약 (model-independent adapter contract)은 어떤 형태여야 할까요?
• 멀티 에이전트 코딩 워크플로우 (multi-agent coding workflows)는 어떻게 리뷰되어야 할까요?
• 실제 리포지토리 (repo)에서 이를 더 쉽게 시도하려면 무엇이 필요할까요?

이 주제에 관심이 있으시다면, 프로젝트에 대한 피드백을 부탁드립니다.

GitHub: https://github.com/SetraTheXX/Codex-Engineering-Workflow-Pack