AI 코딩 에이전트를 조정하기 위한 오픈 소스 로컬 우선 워크벤치 구축기

모든 줄을 수동으로 작성하는 대신, AI 모델에게 구현 제안을 요청하거나, 코드를 생성하게 하거나, 변경 사항 검토를 맡기거나, 실패한 테스트 진단을 돕게 할 수 있습니다.

하지만 여러 모델과 도구를 사용하기 시작하면서 저는 다른 문제를 발견했습니다.

코드를 작성하는 것은 쉬워지고 있었지만, 작업을 조정하는 것은 그렇지 않았습니다.

어떤 기능은 여러 개의 의존적인 작업을 포함할 수 있습니다. 한 모델은 구현을 설계하는 것을 돕고, 다른 모델은 코드를 작성하며, 또 다른 모델은 결과를 검토할 수 있습니다.

하지만 저는 여전히 다음과 같은 질문에 답해야 했습니다:

• 어떤 작업이 먼저 실행되어야 하는가?
• 이 작업을 수행하기에 적합한 모델은 무엇인가?
• 책임 있는 에이전트는 무엇인가?
• 어떤 파일들을 변경할 수 있는가?
• 테스트가 실패하면 어떻게 되는가?
• 구현이 실제로 완료되었다는 것을 어떻게 알 수 있는가?
• 실행 기록은 어디에 보관해야 하는가?

저는 또 다른 필수 클라우드 서비스를 도입하지 않으면서 이 활동들을 연결하고 싶었습니다.

그래서 저는 Accension을 구축하기 시작했습니다.

이것은 Python으로 작성된 오픈 소스, 로컬 우선 AI 모델 라우팅 및 엔지니어링 오케스트레이션 플랫폼입니다.

GitHub: [https://github.com/Jigsaw777/accension]

모델 라우팅에서 엔지니어링 워크벤치로

Accension의 초기 버전은 기능, 품질 증거, 개인정보 보호 정책 및 지출 한도에 따라 AI 모델을 선택하는 데 중점을 두었습니다.

아이디어는 간단했습니다. 다양한 작업이 다른 모델로부터 이점을 얻을 수 있으며, 라우팅은 임의적인 추천보다는 명시적인 제약 조건에 의해 통제되어야 한다는 것입니다.

버전 1.1.0에서는 여기에 Accension Workbench를 추가하여 기능을 확장했습니다.

Workbench는 영속적인 프로젝트(persistent projects), 구조화된 제품 요구사항 문서(Product Requirements Documents, PRDs), 작업 항목(Work Items), 의존성(dependencies), 에이전트 할당(agent assignments), 실행 시도(execution attempts) 및 완료 검토(completion review)를 도입합니다.

가장 중요했던 아키텍처 결정은 별도의 태스크 실행기(task executor)를 구축하는 대신 기존의 실행 엔진을 재사용하는 것이었습니다.

1. 프롬프트가 아닌 요구사항부터 시작하기

간단한 기능을 가정해 봅시다:

"이름과 빈 입력값을 처리하는 인사말 함수를 만들고, 테스트와 문서를 추가한다."

하나의 거대한 프롬프트를 실행하는 대신, 이 요구사항은 구조화된 PRD로 표현될 수 있습니다.

PRD는 목표(objective), 범위(scope), 기능적 요구사항(functional requirements) 및 승인 기준(acceptance criteria)을 정의합니다.

PRD를 검토한 후, 작업은 더 작은 작업 항목들로 분해될 수 있습니다.

예를 들어:

• 인사말 함수 구현하기.
• 이름과 빈 입력값을 커버하는 테스트 추가하기.
• 사용 방법 문서화하기.

이러한 작업들은 의존성을 가질 수 있습니다.

이는 코드 실행이 단순히 화면에 표시되는 순서대로 계획되어서는 안 된다는 점에서 중요합니다.

2. 의존성을 명시적으로 만들기

Accension은 기존의 AXIR 및 ExecutionPlan 계약을 사용하여 실행 가능한 작업 계획(executable task plans)을 나타냅니다.

Workbench는 이러한 계획 위에 영속적인 관리 계층(persistent management layer)을 추가합니다.

이러한 구분은 유용합니다.

작업 항목(Work Item)은 재시작이나 여러 번의 실행 시도에도 살아남을 수 있는 엔지니어링 의무(engineering obligation)를 나타냅니다.

실행 계획(execution plan)은 엔진에 의해 수행될 수 있는 경계가 정해진 작업(bounded work)을 나타냅니다.

Workbench는 작업 항목의 상태와 관계를 저장하는 반면, 기존 실행 인프라는 적격하고 승인된 작업을 수행합니다.

이를 통해 칸반 보드(Kanban board)가 두 번째 실행 엔진이 되는 것을 방지할 수 있습니다.

3. AI 추천과 권한을 분리하기

AI 모델은 기능을 어떻게 분할해야 할지, 그리고 작업자가 어떤 역량(capabilities)을 가져야 하는지에 대해 제안할 수 있습니다.

하지만 추천이 곧 권한(authorization)은 아닙니다.

Accension은 적격성(eligibility), 개인 정보 보호(privacy), 예산(budget), 저장소 권한(repository permissions) 및 실행 정책 검사(execution-policy checks)를 적용합니다.

Workbench에서는 이러한 개념들이 분리된 상태로 유지됩니다:

에이전트 (Agent): 구성된 작업자(worker).

모델 (Model): 추론 백엔드(inference backend).

라우터 (Router): 적격 모델을 결정하는 컴포넌트.

실행 승인 (Execution approval): 검토된 범위를 승인하는 인간의 의사결정.

The 목표는 할당 작업을 설명 가능하게 만들고, AI가 생성한 계획이 스스로 권한을 조용히 확장하는 것을 방지하는 것입니다.

4. 유효성 검사를 별도의 엔지니어링 단계로 취급하기

코딩 어시스턴트와 작업하면서 얻은 가장 중요한 교훈 중 하나는 모델의 최종 메시지가 완료를 입증하는 신뢰할 수 있는 증거가 아니라는 것입니다.

AI는 코드가 컴파일되지 않거나, 테스트에 실패하거나, 요구 사항이 부분적으로만 구현되었을 때에도 성공했다고 보고할 수 있습니다.

따라서 Accension은 실제 실행 시도와 독립적인 호스트 측 검증(host-side validation) 기록을 남깁니다.

시스템은 무슨 일이 일어났는지 설명하는 아티팩트(artifacts)와 실행 영수증(execution receipts)을 보존할 수 있습니다.

인간의 완료 검토가 필요한 경우, 통과한 체크는 필수적인 증거이지만 독립적으로 완료를 승인하지는 않습니다.

Workbench는 또한 PRD 승인, 작업 가져오기(task import), 실행 승인, 그리고 완료 검토를 구분합니다.

이들은 서로 다른 의사결정입니다.

5. 아키텍처를 로컬 우선으로 유지하기

Accension은 Python 백엔드, FastAPI, 그리고 WAL 스토리지를 사용하는 SQLite를 사용합니다.

그의 CLI, Workbench UI, 및 MCP 인터페이스는 공유된 로컬 애플리케이션 상태와 상호 작용합니다.

이러한 설계는 설치를 비교적 가볍게 유지하고 별도의 호스팅 데이터베이스나 메시지 브로커가 필요하지 않도록 합니다.

애플리케이션은 Ollama와 같은 호환 가능한 로컬 런타임을 통해 로컬 모델을 사용할 수 있습니다.

또한 구성된 클라우드 제공업체도 사용할 수 있습니다.

이것은 중요한 개인 정보 보호 차이를 만듭니다: 로컬 프로젝트 저장소가 모든 추론이 로컬이라는 것을 자동으로 의미하지는 않습니다.

승인된 클라우드 요청은 허용된 컨텍스트를 컴퓨터 외부로 전송할 수 있습니다.

애플리케이션은 또한 HTTPS, 페어링(pairing), 및 작업 공간 권한을 통해 선택적 보안 LAN 접근도 지원합니다.

이러한 기능들은 필수적인 호스팅 서비스라기보다는 명시적인 구성 선택 사항입니다.

6. 재현 가능한 데모

저장소에는 유료 추론이 필요하지 않은 결정론적(deterministic) 워크벤치 데모가 포함되어 있습니다.

개발 설치 환경에서:

python scripts/demo_workbench.py --feature

이 데모는 격리된 저장소와 프로필을 생성하고, 의존적인 인사(greeting) 작업을 구성하며, 목업 모델 출력(mock model output)을 사용하고, 실제 로컬 검사를 실행하며, 보존된 영수증(receipts)을 확인합니다.

결과로 나온 스크린샷과 지표는 워크플로우를 보여줍니다. 이는 프로덕션 모델 벤치마크가 아닙니다.

전체 경험을 위해서는 README의 설치 지침을 따르고 Workbench를 여십시오.

제가 배운 점 (What I learned)

Accension을 구축하는 동안 몇 가지 아키텍처 결정이 눈에 띄었습니다.

첫째, 작업 보드(task board)는 단순히 카드를 이동시키는 것이 아니라 실제 실행 상태를 반영해야 합니다.

둘째, 모델 선택과 에이전트 할당은 서로 다른 책임입니다.

셋째, 권한 및 승인 경계는 LLM의 지침이 아닌 애플리케이션 로직에 의해 강제되어야 합니다.

넷째, 실행 기록(execution history)과 영수증은 실제 관찰된 결과를 나타낼 때만 유용합니다.

마지막으로, 개발자 도구는 모든 외부 AI 제공업체가 사용 불가능할 때에도 사용 가능해야 합니다.

이것이 바로 Workbench가 모델 없이도 수동 프로젝트 및 작업 항목(Work Item) 관리를 지원하는 이유입니다.

다음 계획 (What's next?)

저는 다음 영역의 경험 개선에 관심이 있습니다:

• 로컬 모델 워크플로우.
• 에이전트 어댑터(Agent adapters).
• Workbench 사용성.
• 실행 검증(Execution verification).
• 문서화 및 온보딩.
• 기여자 친화적인 예제.

Accension은 Apache 2.0 라이선스 하에 오픈 소스로 공개되었습니다.

저장소: https://github.com/Jigsaw777/accension

이 프로젝트는 Codex Astra의 도움을 받아 구축되었습니다.

여러 코딩 어시스턴트를 사용하거나 로컬 AI 모델을 실험하는 개발자분들의 피드백을 특히 감사히 받겠습니다.

만약 귀하가 로컬 AI 엔지니어링 Workbench를 설계한다면, 가장 중요하다고 생각되는 빠진 기능은 무엇입니까?