vibecode-pro-max-kit: AI 코딩 프로젝트에 스펙, 메모리, 멀티 에이전트 협업 붙이기

AI로 코드를 쓸 때 가장 쉽게 통제가 무너지는 지점은 세 가지입니다. 컨텍스트가 잘리고, 계획이 채팅 기록 여기저기에 흩어지고, 의사결정의 흔적이 남지 않습니다. 요구사항이 한 번 바뀔 때마다 프로젝트 전체를 다시 설명해야 합니다.

vibecode-pro-max-kit은 프로세스 문제를 다룹니다. AI coding agent를 spec-driven engineering team처럼 움직이게 만드는 도구입니다. 먼저 스펙을 쓰고, 그다음 계획하고, 그다음 실행하며, 각 단계는 감사 가능한 기록을 남깁니다. 채팅 framework도 아니고 CI/CD를 대체하지도 않습니다. 한 가지 일을 합니다. AI 코딩의 의사결정 과정을 추적 가능하게 만드는 것입니다.

---

어떤 문제를 해결하나요

컨텍스트 손실: 긴 대화는 compaction으로 잘리고, 설계 결정, boundary condition, debug 과정이 사라집니다. 다음 요구사항 변경 때는 다시 설명하거나 AI가 추측하게 됩니다.

계획과 결정이 기록되지 않음: 채팅 Markdown export는 구조화된 문서가 아닙니다. 팀원이 review할 때 왜 이 방안을 골랐는지, 어떤 선택지를 제외했는지, 어떤 기준이 있었는지 보이지 않습니다.

멀티 에이전트 협업 비용: 하나의 task를 여러 단계로 나누고 각 단계를 다른 agent에게 맡기면 handoff가 모호한 자연어 설명에 기대게 됩니다. 누가 어떤 단계를 맡는지, output format은 무엇인지, acceptance criteria는 어디 있는지 모두 사람이 붙어서 확인해야 합니다.

이 세 가지가 겹치면 AI 코딩은 “매번 처음부터 다시 시작”하는 일이 됩니다. vibecode-pro-max-kit은 이를 하나의 harness로 묶습니다. spec이 앞에 있고, plan이 중간에 있으며, execution에는 checkpoint가 있고, 과정에는 memory가 남습니다.

---

설치 흐름과 보안 감사

설치 명령

README가 제시하는 방식은 원격 shell 설치입니다.

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

설치 후 Claude Code에서는 vc-setup을 실행합니다. Codex 사용자는 README 안내에 따라 /vc-setup을 사용합니다. 이 과정에서 process/ 디렉터리가 생성되고 설정이 초기화됩니다.

작성되는 파일 목록

현재 README는 설치를 non-destructive라고 설명합니다. 기존 .claude/skills/, .claude/agents/, process/, settings.json을 비우지 않고 kit-owned 파일만 작성하거나 업데이트한다는 의미입니다. 그래도 프로젝트에는 다음 디렉터리와 파일이 들어갑니다.

경로	내용
.claude/agents	Claude Code 전용 agent 정의. 현재 README 기준 15개
.claude/skills	Claude Code 전용 skill 정의. 현재 README 기준 33개
.claude/hooks	lifecycle hooks. 현재 README 기준 10개
.codex/agents	Codex에서 사용할 mirrored agents
.agents/skills	Codex discovery를 위한 .claude/skills symlink
CLAUDE.md	Claude Code orchestrator와 routing rules
AGENTS.md	여러 도구에서 공유하는 agent와 skill registry
process/	plan lifecycle과 프로젝트 메모리 디렉터리

README는 기존 설정이 .vibecode-backup/에 백업되고, 기존 CLAUDE.md는 CLAUDE.md.pre-vibecode로 백업된다고 설명합니다. 기존 process/는 설치 script가 직접 migration하지 않고, vc-setup / vc-update가 상호작용 방식으로 처리합니다.

보안 감사 포인트

production repository에서 바로 curl | bash를 실행하지 마세요. README가 non-destructive 설치라고 말하더라도 원격 shell script는 감사가 필요합니다. .claude/, .codex/, CLAUDE.md, AGENTS.md 같은 민감한 경로를 작성하기 때문입니다.

첫 테스트 흐름은 다음이 좋습니다.

1. 비production 프로젝트를 fork하거나 copy합니다.
2. fork 안에서 설치를 실행합니다.
3. git diff로 작성된 파일을 확인합니다.
4. 예상 밖의 설정 변경이 없을 때만 migration을 검토합니다.

설치 script의 백업 메커니즘이 자신의 repository에 맞는지도 직접 검증해야 합니다. 특히 이미 vc- prefix의 custom skill이나 agent가 있는 프로젝트는 README의 caveat를 추가로 확인해야 합니다.

여기서 “덮어쓰지 않는다”는 말은 “위험이 없다”는 뜻이 아닙니다. 기존 디렉터리를 실수로 삭제할 가능성을 낮춘다는 뜻이지, supply chain 감사, 권한 격리, rollback 준비를 생략해도 된다는 뜻은 아닙니다. 팀 프로젝트라면 최소한 script를 읽고, 복사본에서 실행하고, reviewer가 diff를 보는 절차가 필요합니다.

---

핵심 개념: spec-driven workflow

Spec Kit 배경

vibecode-pro-max-kit의 핵심 아이디어는 Spec Kit 같은 spec-driven development(SDD) workflow에서 옵니다. 흐름은 먼저 스펙을 쓰고, 이를 계획으로 구체화하고, task로 나눈 뒤 실행하는 방식입니다.

각 단계는 다음 단계에 구조화된 컨텍스트를 제공하는 Markdown artifact를 생성합니다.

단계	입력	출력
Spec	요구사항 설명	스펙 문서: 경계, 제약, acceptance criteria
Plan	스펙 문서	구현 계획: 단계, 담당, 의존성
Tasks	구현 계획	구체적이고 검증 가능한 task 목록
Implement	task 목록	코드 변경 + 과정 기록

이 흐름 자체는 새롭지 않습니다. 하지만 vibecode-pro-max-kit은 이를 “프로젝트 안에 설치”합니다. agent, skill, hook이 모두 이 흐름을 중심으로 설계됩니다.

계획 lifecycle

현재 README는 RIPER-5 plan-first workflow를 강조하고, 이를 7개의 gated phase로 설명합니다.

단계	하는 일	산출물
Research	배경을 수집하고 경계를 확인	research artifact
Spec	user story와 요구사항 경계를 명확히 작성	spec artifact
Innovate	방안을 비교하고 trade-off 판단	alternatives / decision notes
Plan	단계, 책임, 검증 방식을 구체화	plan artifact
Validate	실행 전 계획과 위험 검증	validation notes
Execute	task에 따라 실행하고 과정 기록	code changes + execution notes
Update-Process	메모리를 업데이트하고 오래된 기록 정리	process / context 업데이트

각 단계는 다음으로 넘어가기 전에 명시적 승인이 필요합니다. 이것이 AI가 엉뚱한 방향으로 달리지 않게 막는 핵심입니다. 사람이 checkpoint에서 개입해 방향을 확인한 뒤에만 다음 단계로 진행합니다.

Agent와 skill

현재 README는 15 agents, 33 skills, 10 hooks를 말합니다. 이는 2026-06-23에 확인한 공식 README 기준입니다. repository 업데이트에 따라 달라질 수 있으므로 영구적인 숫자로 쓰면 안 됩니다.

skill 구조는 Codex Skills, Claude Code skills와 같습니다. 각 skill에는 instruction인 SKILL.md가 있고, 선택적으로 scripts/, references/, assets/가 있습니다. skill은 명시적으로 호출될 수도 있고, 매칭되는 경계 안에서 암시적으로 trigger될 수도 있습니다.

또 다른 두 가지 개념도 있습니다.

• context groups: 주제나 기능별로 구성한 컨텍스트 블록입니다. 매번 전체 프로젝트를 로드하지 않기 위한 구조입니다.
• feature folders: 기능 모듈별로 파일을 조직하며, 각 folder가 자체 spec과 process를 가집니다.

---

보안 메커니즘 상세

README는 주목할 만한 보안 및 프로세스 메커니즘을 몇 가지로 정리합니다.

메커니즘	역할	trigger 시점
privacy guardrails	민감한 정보가 process나 output에 들어가지 않게 차단	agent output과 process update 전
gated phases	agent가 바로 코드 작성으로 건너뛰지 못하게 차단	Research부터 Update-Process까지 단계 전환
check loops	실행 과정이 스스로 확인하고 계획으로 돌아가게 함	실행 및 검증 단계
deviation protocol	원래 계획에서 벗어난 행동을 기록	plan이 수정되거나 실행이 벗어날 때
high-risk evidence pack	고위험 결정에 추가 근거 요구	특정 판단 threshold가 trigger될 때

이런 메커니즘은 AI가 감독 없이 고위험 결정을 내리기 어렵게 만듭니다. 하지만 hook과 설정이 제대로 동작한다는 전제가 있습니다. hook이 비활성화되어 있거나, 권한이 너무 넓거나, 팀이 process/를 review하지 않으면 여전히 효과가 떨어질 수 있습니다.

---

적용 시나리오 판단표

시나리오	적합한가	이유
장기 유지보수 프로젝트	적합	메모리가 process/에 쌓이고 계획을 감사할 수 있음
여러 명의 review	적합	결정과 deviation을 추적 가능
복잡한 요구사항	적합	멀티 에이전트 협업과 단계별 구체화
컨텍스트가 쉽게 사라지는 작업	적합	spec-driven 구조화 대화
일회성 script	덜 적합	프로세스 overhead가 큼
작은 수정	덜 적합	harness 도입 비용이 이익보다 큼
이미 성숙한 engineering process	신중	기존 CI/CD나 review 흐름과 충돌할 수 있음
외부 harness를 들이고 싶지 않음	부적합	README, AGENTS.md, CLAUDE.md, process가 repository 구조를 바꿈

핵심 판단은 프로세스 overhead가 가치가 있는가입니다. 장기적이고 복잡하며 협업이 많은 프로젝트에서는 overhead가 감사 가능성과 협업 효율로 돌아옵니다. 짧고 단순하며 혼자 하는 프로젝트에서는 overhead가 비용으로만 남습니다.

---

Spec Kit, Codex Skills, Claude Code와의 관계

Spec Kit: SDD, 즉 spec-driven development의 배경과 workflow framework를 정의합니다. 특정 agent에 묶이지 않는 개념 계층입니다.

Codex Skills: OpenAI의 skill 디렉터리 구조입니다. SKILL.md + scripts/ + references/로 구성되며, instruction, resource, script를 재사용 가능한 workflow로 포장합니다.

Claude Code skills: 구조는 비슷합니다. SKILL.md와 지원 파일을 사용합니다. skill을 재사용 가능한 프로세스 단위로 보고, 명시적 또는 암시적으로 호출할 수 있습니다.

vibecode-pro-max-kit: 위 아이디어를 프로젝트 안에 넣습니다. Spec Kit을 대체하는 것이 아니라 spec-driven 흐름을 실행 가능한 agents + skills + hooks로 구성하고, Claude Code와 Codex의 프로젝트 설정과 함께 쓰게 합니다.

Migration 비용: 프로젝트에 이미 .claude/agents, .claude/skills, CLAUDE.md, AGENTS.md가 있다면 diff를 평가하고 자신의 custom 설정이 사라지지 않았는지 확인해야 합니다.

---

첫 테스트 절차

README 권장처럼 첫 테스트는 production이 아닌 프로젝트에서 진행합니다.

1단계: 비production 프로젝트를 fork하거나 copy하기

main repository에서 바로 작업하지 않습니다. fork repository나 로컬 테스트 디렉터리 복사본을 사용합니다.

2단계: 설치 명령 실행

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

3단계: vc-setup 실행

Claude Code에서는 vc-setup을 실행합니다. Codex에서는 README 안내에 따라 /vc-setup을 사용합니다. 이 과정에서 process/ 디렉터리가 생성되고 설정이 초기화됩니다.

4단계: 파일 작성 내용 확인

git status
git diff .claude/ .codex/ .agents/ CLAUDE.md AGENTS.md process/

작성된 파일이 예상과 맞는지 확인합니다.

5단계: 첫 spec-driven workflow 시도

agent에게 “logging 함수 하나 추가” 같은 간단한 요구를 줍니다. Research -> Spec -> Innovate -> Plan -> Validate -> Execute -> Update-Process 과정을 관찰하고, 각 단계에서 승인 메커니즘이 trigger되는지 확인합니다.

6단계: 검수

process/ 디렉터리에 산출물이 생기고, CLAUDE.md / AGENTS.md 변경 내용을 이해할 수 있으며, hooks와 agents에서 오류가 없다면 그때 실제 프로젝트 migration을 검토합니다.

---

다음 단계와 함께 읽을 글

이미 게시된 관련 글:

• OpenClaw 멀티 에이전트 routing 실전
• Claude Code workflow 전체 가이드
• AI agent 메모리 메커니즘 해설

시리즈 후속 콘텐츠:

• 멀티 에이전트 협업 troubleshooting checklist
• spec-driven 프로젝트 실전 사례