AI 코딩 에이전트(AI coding agents)는 인상적입니다. 그들은 구문(syntax)이 정확한 코드를 작성합니다. 수천 개의 라이브러리를 알고 있습니다. 당신이 설명하는 무엇이든 몇 초 만에 구현할 수 있습니다. 그리고 그것이 바로 문제입니다.

속도의 함정 (The Speed Trap)
당신은 기능을 설명합니다. 에이전트는 코드를 생성합니다. 당신은 그것을 배포(ship)합니다. 작동합니다. 잠시 동안은 말이죠. 그러다 요구사항이 변경됩니다. 팀이 성장합니다. 시스템이 확장됩니다. 코드베이스(codebase)는 신비롭지만 완전히 예측 가능한 방식으로 유지보수 불가능해집니다. 코드는 작동했습니다. 하지만 아키텍처(architecture)는 설계된 적이 없었습니다. 저도 그런 경험이 있습니다. Claude에게 작업을 주었고, 그것은 바로 코드로 뛰어들었습니다. 저는 그것을 배포했고, 3개월 후 아키텍처가 없었기 때문에 완전히 새로 작성해야 했습니다.

시니어 엔지니어가 실제로 하는 일
스태프 엔지니어(Staff Engineer)가 새로운 작업에 접근하는 방식을 지켜보십시오. 그들은 에디터(editor)를 열지 않습니다. 질문을 던집니다. 기존 코드를 읽습니다. 다이어그램(diagrams)을 그립니다. 다른 누군가가 이것을 유지보수할 18개월 후에 어떤 일이 일어날지 생각합니다. 그들은 결정을 문서화합니다. 자신을 방어하기 위해서가 아니라, 미래의 컨텍스트(context)가 현재의 코드만큼 가치 있다는 것을 알기 때문입니다. 그들이 구현의 첫 번째 줄을 쓰기 전까지, 그들은 이미 알고 있습니다:

• 왜 대안 대신 이 아키텍처가 선택되었는지
• 실패 모드(failure modes)는 무엇이며 어떻게 처리되는지
• 시스템이 성장함에 따라 어디를 변경해야 할지
• 새로운 개발자가 이 작업을 수행하기 위해 무엇을 이해해야 하는지

통제되지 않은 AI 에이전트들은 이 모든 과정을 건너뜁니다. 그들은 시스템의 장기적인 건강함이 아니라, 즉각적인 요청에 최적화합니다.

격차 (The Gap)
이것은 도구의 문제가 아닙니다. 프로세스(process)의 문제입니다. 저는 그 격차를 메우기 위해 Kavro를 만들었습니다. Kavro는 어떤 AI 코딩 에이전트 위에서도 7단계의 스태프 수준 엔지니어링 워크플로우(workflow)를 강제하는 오픈 소스 프레임워크(open-source framework)입니다.

7단계 (지름길 없음)
1단계: 심층 조사 및 이해 (Deep Research & Understanding)
비즈니스 목표, 기술적 컨텍스트(technical context), 도메인 패턴(domain patterns), 그리고 리스크를 이해합니다. 조사 요약(Research Summary)을 생성합니다. 코드인가요? 아닙니다.

2단계: 시스템 설계 및 아키텍처 (System Design & Architecture) API 계약 (API contracts), 데이터 설계 (data design), 에러 처리 전략 (error handling strategy), 그리고 모든 주요 선택에 대한 결정 로그 (decision log)를 포함한 완전한 기술 청사진 (Technical Blueprint)을 생성합니다. 코드인가요? 아닙니다.

3단계: 작업 분해 (Task Decomposition) 명시적인 의존성 (dependencies), 범위 (scope), 그리고 검증 단계 (validation steps)를 포함하여 프로젝트를 원자적이고 독립적으로 검증 가능한 작업들로 나눕니다. 코드인가요? 아닙니다.

4단계: 문서화 (Documentation) 구현 전에 문서화 기준점 (documentation baseline)을 수립합니다. 코드인가요? 아닙니다.

5단계: 프롬프트 오케스트레이션 (Prompt Orchestration) 1~4단계를 기반으로 각 작업에 대해 정밀하고 컨텍스트가 주입된 (context-injected) 프롬프트를 생성합니다. 코드인가요? 아닙니다.

6단계: 에이전트 선택 (Agent Selection) 복잡도에 따라 어떤 에이전트(또는 모델 계층 (model tier))가 각 작업을 처리할지 결정합니다. 코드인가요? 아직은 아닙니다.

7단계: 거버넌스 (Governance) 청사진 (blueprint)에 따라 출력을 검증하면서 지속적으로 실행합니다. 드리프트 (drift)를 포착합니다. 이제 코드를 작성할 수 있습니다. 그리고 그것은 훌륭한 코드입니다.

이것이 작동하는 이유
최고의 엔지니어는 해결책으로 바로 뛰어들지 않습니다. 그들은 문제를 깊이 이해합니다. Kavro는 그 규율 (discipline)을 자동화합니다. AI 에이전트는 앞서 나갈 수 없습니다. 느낌대로 코딩하는 것 (vibe-coding)도 할 수 없습니다. 결정을 나중으로 미룰 수도 없습니다. 워크플로우 (workflow)가 강제됩니다.

실제 모습
사용자: "알림 서비스(notification service)를 만들어줘"

Kavro 없이:
→ Claude가 즉시 코드를 작성함

Kavro 사용 시:
→ 1단계: 비즈니스 목표, 리스크, 기술적 컨텍스트에 대해 질문함
→ 조사 요약 (Research Summary) 생성
→ 2단계: 완전한 결정 문서화가 포함된 기술 청사진 (Technical Blueprint) 생성
→ 3단계: 의존성이 포함된 작업 분해 (Task decomposition)
→ 4단계: 문서화 구조 수립
→ 5~7단계: 지속적인 검증을 동반한 오케스트레이션된 실행
→ 결과: 확신을 가지고 배포

오픈 소스
Kavro는 MIT 라이선스이며 다음 환경에서 작동합니다:
Claude Code
Claude.ai
Codex CLI
Cursor
Windsurf

aventskills.io의 오픈 표준 (open standard)을 기반으로 구축되었으므로, 도구에 종속되지 않고 개발자와 함께 이동합니다.

GitHub: https://github.com/a7medalyapany/kavro

설치 (Installation)

git clone https://github.com/a7medalyapany/kavro.git
cd kavro
bash scripts/install.sh

Claude.ai를 위한 업로드:
bash scripts/build.sh --claude

dist/kavro-claude.zip 업로드 → Settings → Skills

장기적 비전 (The Long Vision)

Kavro v1.0은 하나의 스킬 (skill)입니다. 즉, AI 에이전트 (AI agent)를 감싸는 지침 (instructions)입니다. 더 나아가 장기적인 비전은 세션 전반에 걸쳐 아키텍처 결정 (architectural decisions)을 추적하고, 시간이 지남에 따라 발생하는 드리프트 (drift)를 감지하며, 엔지니어링 팀에게 AI 에이전트가 시스템을 어떻게 구축하고 있는지에 대한 가시성 (visibility)을 제공하는 거버넌스 서비스 (governance service)입니다. 이는 감시 (surveillance)가 아닙니다. 책임 (accountability)입니다.

팀을 위한 기능 (For Teams)

만약 팀에서 서로 다른 AI 도구들을 사용한다면 (누군가는 Claude를, 누군가는 Cursor를, 누군가는 Codex를 사용하는 경우), Kavro는 이 모든 도구에 대해 동일한 규율 (discipline)을 강제합니다. 하나의 프레임워크 (framework), 여러 개의 에이전트 (multiple agents).

Kavro의 핵심 신념은 간단합니다: 깊이 이해된 문제는 이미 절반은 해결된 것이나 다름없습니다. 아키텍처 (architecture) 없이 작성된 코드는 설계 단계부터 기술 부채 (technical debt)입니다. Kavro는 AI 에이전트가 시니어 엔지니어 (senior engineer)처럼 생각하게 만듭니다. 이는 "지금 작동하는 것"과 "영원히 작동하는 것"의 차이입니다.

AI가 생성한 코드를 다시 작성해야 했던 경험이 있다면, 스타 (star)를 눌러주세요. 구축하기 전에 생각하십시오.