Aura 구축하기: 당신이 제어할 수 있는 오픈 소스 AI 코딩 하네스 (Harness)

원래 Hashnode에 게시되었습니다: [(https://aura-ide.hashnode.dev/building-aura-an-open-source-ai-coding-harness-you-can-control?utm_source=hashnode&utm_medium=feed)]

하네스를 소유하세요: 계획을 확인하고, 수정을 검사하며, 결과를 신뢰할 수 있는 AI 코딩 도구

AI 코딩 도구들은 강력하지만, 그 워크플로 (workflow)는 종종 불안정하게 느껴집니다.
당신은 변경 사항을 요청합니다. 에이전트 (agent)는 몇몇 파일들을 읽습니다. 무언가를 수정합니다. 아마도 명령어를 실행할 수도 있습니다. 혹은 작업이 완료되었다고 말할 수도 있습니다.

하지만 사용자로서 당신은 종종 다음과 같은 의문을 갖게 됩니다:

실제로 어떤 계획을 세웠는가?
어떤 파일들을 건드렸는가?
쓰기 작업이 실제로 적용되었는가?
검증 (validation)이 실행되었는가?
실제 문제를 해결하고 있는가, 아니면 노이즈에 대해 허우적거리고 있는가?
어제 내가 신뢰했던 도구와 오늘 사용하고 있는 도구 사이에 무엇이 변했는가?

Aura는 이러한 신뢰 문제(trust problem)를 중심으로 AI 코딩 환경을 구축하려는 저의 시도입니다.

이것은 Planner/Worker 아키텍처 (architecture), 안전한 파일 수정, 가시적인 워크플로 상태, 프로바이더 (provider) 유연성, 지속적인 프로젝트 메모리, MCP 통합, 그리고 AI가 생성한 흔한 코드 슬롭 (slop, 저질 코드)을 줄이기 위해 설계된 코드 품질 검사 단계인 Craft를 갖춘 로컬 오픈 소스 AI 코딩 하네스 (harness)입니다.

목표는 단순히 모델이 코드를 작성하게 만드는 것이 아닙니다.

목표는 전체 프로세스를 검사 가능하게 (inspectable) 만드는 것입니다.

핵심 아이디어: 하네스를 소유하라

대부분의 AI 코딩 워크플로는 타인에 의해 제어됩니다.

인터페이스가 변합니다. 모델의 동작이 변합니다. 제한 사항이 변합니다. 당신이 습관을 들여온 워크플로가 갑자기 다르게 느껴질 수 있습니다.

Aura가 오픈 소스인 이유는 저는 그 반대를 원하기 때문입니다.

만약 특정 버전이 당신에게 잘 맞는다면, 그것을 계속 유지할 수 있습니다. 만약 프로바이더가 변경된다면, 교체할 수 있습니다. 만약 워크플로가 당신의 사고 방식에 맞지 않는다면, 수정할 수 있습니다.

Aura는 하네스 그 자체를 제품으로 취급합니다.

단순히 모델만이 아닙니다.

단순히 채팅창만이 아닙니다.

하네스 (Harness): 컨텍스트가 어떻게 수집되는지, 계획이 어떻게 수립되는지, 수정 사항이 어떻게 적용되는지, 실패가 어떻게 보고되는지, 품질이 어떻게 확인되는지, 그리고 사용자가 어떻게 제어권을 유지하는지에 대한 것입니다.

Planner (계획자) 및 Worker (작업자)

Aura는 사고(thinking)와 실행(execution)을 분리합니다.

Planner는 요청을 이해하고, 컨텍스트 (context)를 조사하며, 집중된 구현 명세 (implementation spec)를 작성하는 책임을 집니다.

Worker는 실제 코드베이스 작업을 수행하는 책임을 집니다: 파일을 읽고, 수정을 적용하며, 명령어를 실행하고, 발생한 일을 보고합니다.

이러한 분리가 중요한 이유는 단일 에이전트 코딩 (single agent coding)이 종종 서로 다른 작업들을 하나의 무질서한 루프 (loop)로 뭉뚱그려 버리기 때문입니다. 동일한 모델이 사용자를 이해하고, 저장소 (repo)를 검색하고, 아키텍처를 결정하고, 파일을 수정하고, 디버깅 도구를 사용하며, 결과를 요약하는 일을 동시에 시도합니다.

Aura는 이러한 책임들에 더 명확한 경계를 부여합니다.

Planner는 다음 질문에 답해야 합니다:

무엇이 변경되는가?
왜 변경하는가?
어떤 파일들이 연관될 가능성이 높은가?
완료된 상태는 어떤 모습인가?
실제로 Worker를 파견해야 하는가?

Worker는 다음 질문에 답해야 합니다:

무엇을 읽었는가?
무엇을 수정했는가?
쓰기 (write)가 적용되었는가?
어떤 검증 (validation)이 실행되었는가?
여전히 주의가 필요한 부분은 무엇인가?

get_workspace_snapshot 및 run_diagnostic_command와 같은 최신 Planner 진단 도구들은 Planner가 Worker를 파견할지 결정하기 전에 현재 워크스페이스 (workspace) 상태를 조사할 수 있도록 돕습니다.

이는 좋은 계획이 저장소에 대해 실제로 무엇이 사실인지 아는 것에서부터 시작되기 때문에 중요합니다.

안전한 쓰기 및 가시적인 결과

Aura의 가장 중요한 규칙 중 하나는 간단합니다:

쓰기 결과가 실제로 적용되지 않았다면, 그것은 성공이 아닙니다.

당연하게 들릴 수 있지만, 이는 AI 코딩 워크플로 (workflow)가 사용자의 신뢰를 조용히 잃을 수 있는 지점 중 하나입니다.

도구는 파일을 변경하지 않은 채로 깔끔하게 반환될 수 있습니다. 패치 (patch)가 적용되지 않을 수 있습니다. 심볼 (symbol) 수정이 대상을 놓칠 수 있습니다. 검증 명령어는 수정 사항과 무관한 이유로 실패할 수 있습니다.

Aura는 쓰기 결과를 명시적으로 추적합니다. 워크플로는 이러한 상태들을 가시화하도록 설계되었습니다:

적용됨 (applied)
적용되지 않음 (not applied)
후속 조치 필요 (needs follow-up)
검증 실패 (validation failed)
Craft에 의해 차단됨 (Craft blocked)
편집 메커니즘 실패 (edit mechanics failed)
하네스 오류 (harness error)

이를 통해 AI 코딩의 가장 최악의 실패 모드 중 하나인 가짜 완성 (fake completion)을 방지합니다.

만약 Aura가 패치 (patch)를 적용하지 못했다면, 적용한 것처럼 가장해서는 안 됩니다.

Craft: 과도한 수정 없는 코드 품질 관리

Craft가 존재하는 이유는 LLM이 생성한 코드에 특유의 질감 (texture)이 있는 경우가 많기 때문입니다.

기능적으로는 작동할지 몰라도, 다음과 같은 미세한 흔적들이 가득할 수 있습니다:

설명조의 주석 (narration comments)
플레이스홀더 구조 (placeholder scaffolding)
범용적인 헬퍼 함수들의 나열 (generic helper soup)
장식용 배너 (decorative banners)
무의미한 추상화 (pointless abstraction)
예외 무시 (swallowed exceptions)
가짜 완성도 (fake completeness)

Craft는 Aura의 품질 검사 (quality pass) 단계입니다. Craft의 역할은 거부감을 주지 않으면서 흔한 AI 슬롭 (slop, 저품질 코드)을 정리하고 실제 위험 요소를 잡아내는 것입니다.

설계 철학은 다음과 같습니다:

Craft가 안전하게 정리할 수 있다면, 조용히 정리한다.
Craft가 단순히 스타일이 마음에 들지 않는 것이라면, 경고한다.
Craft가 코드가 깨질 것을 안다면, 차단한다.

이러한 구분은 매우 중요합니다.

초기 버전의 Craft는 너무 엄격하여 수정 루프 (repair loops)를 유발할 수 있었습니다. 신뢰도가 낮은 정적 분석 (static analysis) 경고가 하드 실패 (hard failure)처럼 취급될 수 있었고, 이는 워커 (Worker)가 앞으로 나아가는 대신 과도하게 수정 작업을 반복하는 스래싱 (thrash) 현상을 일으켰습니다.

최근 작업에서는 신뢰도가 낮은 진단 결과는 경고 (warning)로 처리하고, 하드 블로커 (hard blocker)는 그대로 유지하도록 시스템을 조정했습니다.

하드 블로커 (Hard blockers)에는 다음과 같은 항목이 포함됩니다:

구문 오류 (syntax errors)
명백한 스텁 본문 (obvious stub bodies)
명시적인 계약 위반 (explicit contract violations)
안전하지 않은 파괴적 작업 (unsafe destructive operations)
정의되지 않은 이름 도입 (introduced undefined names)
깨진 임포트 도입 (introduced broken imports)

경고 (Warnings)에는 다음과 같은 항목이 포함됩니다:

추측된 호출 시그니처 관련 우려 (guessed call signature concerns)
누락된 속성 관련 우려 (missing attribute concerns)
일반적인 스타일 문제 (generic style issues)
권고 사항으로서의 코드 품질 관찰 (advisory code quality observations)

Craft는 Aura가 스스로와 싸우고 있다는 느낌을 주지 않으면서 코드를 더 좋게 만들어야 합니다.

목표는 두 번째 화난 컴파일러 (compiler)를 만드는 것이 아닙니다.

목표는 생성된 코드가 덜 생성된 것처럼 느껴지게 만드는 것입니다.

토큰 낭비 없는 메모리

Aura는 프로젝트에 대한 이해를 로컬에 지속적으로 저장합니다.

세 가지 계층이 있습니다:

재시작 시에도 검색 속도를 빠르게 유지하기 위한 BM25 코드베이스 인덱스 (codebase index).
Planner에게 프로젝트의 압축된 구조적 뷰를 제공하는 AST 기반 리포 맵 (repo map).
완료된 작업 및 저장된 노트를 위한 SQLite FTS5 프로젝트 메모리 데이터베이스 (project memory database).

목표는 모델이 매 세션마다 동일한 프로젝트를 다시 발견하는 데 비용을 지불하지 않도록 하는 것입니다.

Aura는 유용한 프로젝트 컨텍스트를 로컬에 유지하고, 검색 가능하며, 재사용할 수 있도록 할 수 있습니다. 코드와 메모리는 모델 제공자 (model provider)에게 명시적으로 전송되지 않는 한 머신에 그대로 유지됩니다.
BM25 캐시 (cache)는 코드베이스 검색을 빠르게 만듭니다.
리포 맵 (repo map)은 Planner에게 클래스 (classes), 함수 (functions), 시그니처 (signatures)에 대한 경량화된 구조적 뷰를 제공합니다.

프로젝트 메모리 데이터베이스는 목표, 사양 (specs), 수정된 파일, 결과 및 노트를 포함하여 완료된 Worker 배정 기록 (dispatch records)을 저장합니다. 이는 Aura가 결국 과거의 결정을 처음부터 다시 발견하는 대신 회상할 수 있음을 의미합니다.

메모리는 단순히 편의성에 관한 것이 아닙니다.

그것은 연속성 (continuity)에 관한 것입니다.

MCP 및 도구 생태계 (tool ecosystems)

Aura는 또한 MCP를 통해 더 넓은 도구 생태계에 맞도록 설계되었습니다.

Aura가 폐쇄된 섬이 되는 것이 목표가 아닙니다. Aura는 외부 도구를 사용하고, 유용한 기능을 노출하며, 하나의 앱이나 하나의 제공자를 넘어 확장되는 워크플로 (workflows)에 참여할 수 있습니다.

이는 동일한 핵심 아이디어와 일치합니다: 하네스 (harness)는 개발자의 소유여야 합니다.

도구, 제공자, 프로젝트 메모리 및 워크플로 규칙은 단일 인터페이스 뒤에 갇히는 대신 조합 가능 (composable)해야 합니다.

제공자 유연성 (Provider flexibility)

Aura는 하나의 모델 회사에 묶여 있지 않습니다.

하네스는 제공자가 변경될 수 있도록 설계되었습니다. 원격 API (remote APIs), 로컬 모델 (local models), 또는 작업에 적합한 무엇이든 사용할 수 있습니다.

AI 코딩 분야는 끊임없이 변하기 때문에 이것은 중요합니다. 모델은 개선되기도 하고, 퇴보하기도 하며, 가격이 재조정되거나, 사라지거나, 동작이 변하기도 합니다.

Aura의 목표는 제공자가 변경되더라도 워크플로를 안정적으로 유지하는 것입니다.

모델이 변경되더라도 하네스는 여전히 작업을 검사 가능 (inspectable)하게 유지해야 합니다.

제공자가 변경되더라도 프로젝트 메모리는 여전히 당신의 것이어야 합니다.

특정 버전이 당신에게 잘 맞는다면, 당신은 그것을 계속 유지할 수 있어야 합니다.

로컬 퍼스트 (Local first)가 중요한 이유

로컬 퍼스트 (Local first)가 모든 모델을 반드시 로컬에서 실행해야 한다는 의미는 아닙니다.

이는 프로젝트, 메모리, 워크플로우 (workflow), 그리고 제어 인터페이스 (control surface)가 사용자에게 귀속되어야 함을 의미합니다.

Aura는 API를 사용할 수 있지만, 하네스 (harness)가 API 제공자에게 속해서는 안 됩니다. 저장소 (repo), 프로젝트 메모리, 규칙, 워크플로우 상태, 그리고 릴리스 버전은 당신의 것으로 남습니다.

이것이 코딩 워크플로우를 임대하는 것과 소유하는 것의 차이입니다.

Aura가 되고자 하는 모습

장기적인 방향은 개발자가 실제로 일하는 방식에 맞춰 형성될 수 있는 AI 코딩 하네스 (AI coding harness)가 되는 것입니다.

즉, 다음과 같은 특징을 가집니다:

오픈 소스 코어 (open source core)
가시적인 계획 (visible planning)
안전한 쓰기 (safe writes)
제공자 교체 (provider swapping)
로컬 프로젝트 메모리 (local project memory)
코드 품질 검사 (code quality checks)
워크플로우 커스터마이징 (workflow customization)
궁극적으로는 Aura 자체의 성공적인 세션으로부터 얻은 학습 데이터 (training data)

Aura의 가장 흥미로운 미래 버전은 단순한 앱이 아닙니다.

그것은 모델에게 그 내부에서 어떻게 행동해야 하는지를 가르칠 수 있는 하네스 (harness)입니다.

Aura는 이미 완료된 작업에 대한 구조화된 디스패치 데이터 (structured dispatch data)를 기록하고 있습니다: 목표 (goals), 사양 (specs), 수정된 파일 (touched files), 결과 (outcomes), 검증 (validation), 그리고 수정 노트 (repair notes) 등입니다. 시간이 흐름에 따라 이러한 기록들은 큐레이션된 학습 예시 (training examples)가 될 수 있습니다.

이것의 미래 버전은 Aura 네이티브 데이터셋 (Aura native dataset)입니다:

작업 (task)
저장소 컨텍스트 (repo context)
계획 (plan)
도구 호출 (tool calls)
쓰기 결과 (write outcomes)
Craft 결과 (Craft results)
검증 (validation)
최종 요약 (final summaries)

해당 데이터는 궁극적으로 Aura 네이티브 채팅, 플래너 (planner), 그리고 코더 (coder) 모델을 학습시킬 수 있습니다.

범용 코딩 모델이 아닙니다.

Aura의 워크플로우를 이해하는 모델입니다.

단순히 코드를 작성하는 것뿐만 아니라, 실제 코딩 하네스 (coding harness) 내부에서 행동하도록 학습된 모델입니다: 편집하기 전에 읽기, 신중하게 패치하기, 도구 결과 존중하기, 잘못된 성공 피하기, 가능한 경우 검증하기, 그리고 무의미한 반복 (thrashing) 멈추기 등입니다.

핵심 요점

Aura가 존재하는 이유는 AI 코딩이 에이전트가 실제로 작업을 수행했는지 추측해야 하는 과정처럼 느껴져서는 안 되기 때문입니다.

당신은 계획을 보고, 편집 내용을 검사하며, 결과를 이해하고, 워크플로우에 대한 제어권을 유지할 수 있어야 합니다.

이것이 우리의 베팅입니다.

하네스를 소유하십시오.

무엇이 변했는지 확인하십시오.

적용된 내용을 신뢰하십시오.

Aura는 오픈 소스입니다:

https://github.com/CarpseDeam/Aura-IDE

만약 이 프로젝트가 당신의 공감을 불러일으키고 지속적인 개발을 지원하고 싶다면:

https://buymeacoffee.com/snowballkori