서론

2026/6/13 Fable 5는 사용할 수 없게 되었습니다.

부활은 아무래도 어려울 것 같아, 개인적으로 진행했던 작업을 기록으로 남기기 위해 기사를 작성합니다.

본론

GitHub Copilot의 사실상의 가격 인상을 계기로, "개인이 코딩 에이전트(Coding Agent)를 부담 없이 계속 사용할 수 없게 되지 않을까"라는 우려가 생겨났습니다. 그 대책으로서, 내 컴퓨터의 로컬 LLM(Local LLM)만으로 동작하는 코딩 에이전트 **lca (Local Coding Agent)**를 만들기로 했습니다. 코드를 일절 클라우드로 보내지 않고, 월간 구독료나 API 과금에도 얽매이지 않고 "설계 → 역할별 구현 → 검증"의 사이클을 돌리는 것을 목표로 했습니다.

처음에 세운 가설은 **"평소 프로그램 개발에서 수행하는 프로세스를 논리적으로 분할할 수 있다면, 각 단계에서 필요한 사고는 로컬 LLM으로도 충분히 해낼 수 있다"**는 것이었습니다. 로컬 LLM 모델은 거대 모델처럼 "통째로 맡기면 알아서 똑똑하게 해주는" 방식이 아닙니다. 하지만 설계, 구현, 리뷰와 같은 공정으로 나누고 각 공정의 입력과 출력을 명확히 하면, 하나하나의 판단은 그렇게 고도화될 필요가 없어집니다. 그렇다면 모델의 지능이 아니라 구조(Structure) 측면에서 성립시킬 수 있을 것이라고 생각했습니다.

이 기사는 코드를 소개하는 것이 아니라, 그 설계 방식에 초점을 맞춘 해설입니다. 클라우드의 거대 모델을 전제로 한 에이전트 설계를 그대로 로컬 모델에 가져오면 파탄 난다고 생각했습니다. 그 차이를 어떻게 메웠는지——다시 말해 **"똑똑하지 않은 모델을 전제로 한 설계"**란 무엇인지——를 아키텍처와 처리 흐름의 관점에서 정리합니다.

무엇을 만들었는가

lca는 자연어 요청을 받아 워크스페이스 내의 파일을 읽고 쓰며 코딩 태스크를 완료하는 도구입니다. 내부 구성은 하나의 팀으로 이루어져 있습니다.

설계 담당(Architect): 요청을 인터페이스 계약과 태스크로 분해함
구현 담당(Worker): 1개 태스크를 구현 및 검증함. Backend / Frontend / Python / QA 등 여러 전문성을 가짐
리뷰 담당(Reviewer): 변경 사항(Diff)이 요청과 설계를 충족하는지 판정함

UI는 터미널(대화형 / 1회 실행)과 로컬 Web 화면 두 가지입니다. 파일 변경과 커맨드 실행은 기본적으로 1건씩 인간의 승인을 요구합니다.

기술 스택

설계 원칙으로서 의존성을 낮게 유지하는 것을 철저히 하고 있습니다. NuGet 패키지에 대한 의존은 앱 본체에서 실질적으로 1개(에이전트 기반)뿐이며, 차분 생성(Diff generation)·커맨드 분류·JSON 추출·설정·승인 등은 .NET 표준 라이브러리로 구현했습니다. OpenAI 호환 서버별 차이도 한 곳에 가두어 프레임워크 업데이트의 영향을 최소화했습니다.

설계의 출발점: 로컬 LLM의 3가지 제약

설계 판단은 로컬 모델이 가진 다음 제약으로부터 역산되었습니다.

"모델을 똑똑하게 만드는" 것이 아니라 "똑똑하지 않아도 성립하는 구조"를 만드는 방향으로 진행했습니다.

아키텍처 전체상

중심에 있는 것은 LLM이 아니라, **결정론적인 코드인 관리자(Orchestrator)**입니다. LLM이 판단하는 것은 "설계와 태스크의 내용" "코드의 변경 내용" "리뷰의 지적 사항"뿐입니다. 진행·순서·재시도(Retry)·중단은 모두 관리자가 결정합니다.

중요한 구조적 판단은 3가지입니다.

• 관리자는 LLM이 아니다: 로컬 LLM에게 다른 에이전트의 관리까지 맡기면 상태를 놓치기 쉬우므로, 협조는 모두 관리자(결정적인 코드)를 통해 이루어집니다.
• 에이전트 간의 직접 대화는 없다: 대화 로그를 다음 에이전트에게 전달하지 않습니다. 전달하는 것은 '설계 방침'과 '선행 태스크의 결과 요약'뿐입니다.
• 부작용(Side Effect)을 가질 수 있는 것은 Worker뿐이다: Architect / Reviewer는 '입력 → JSON'의 1회 왕복 순수 함수(Pure Function)로 취급합니다. 후술할 검사 단계(Inspector 등)는 읽기 전용 도구만 가지며, 스스로 코드를 변경하지 않습니다

등장하는 모든 에이전트와 조직도

에이전트는 3개 층으로 나뉩니다. 관리자로부터 직접 호출되는 제어 흐름상의 3역, 그 Worker가 내부에 가진 전문성, 그리고 승인 정밀도를 높이는 추가 검사 단계입니다. 먼저 관리자로부터 호출되는 에이전트의 전체 모습입니다.

1. 제어 흐름상의 3역

2. Worker의 전문성 (프롬프트 합성으로 표현)

Worker는 한 종류의 에이전트이지만, 할당된 역할에 따라 시스템 프롬프트(System Prompt)를 합성하여 '전문가'가 됩니다. 공통 규범에 역할별 추가 규범을 연결할 뿐이므로, 역할이 늘어나도 제어 흐름은 늘어나지 않습니다.

3. 승인 정밀도를 높이는 추가 검사 단계

차분 리뷰(Diff Review)만으로는 '실행하면 망가지는 경우'나 '기획 의도를 충족하지 못하는 경우'를 놓칠 수 있습니다. 그래서 조건부로 기동하는 검사 단계를 겹쳐 두었습니다.

여기서 적용되는 원칙은 **'수정 권한을 가진 것은 Worker뿐이다'**입니다. Inspector / Director / Analyst는 읽기 전용 도구만 가지며, 발견한 문제는 지적으로 관리자에게 반환할 뿐입니다. 실제 수정은 관리자가 수정 라운드로서 Worker에게 돌립니다. 검사와 수정을 분리함으로써, 검사역이 멋대로 코드를 바꿔버리는 사고를 방지합니다. PlayCheck와 Vision은 애초에 LLM 에이전트가 아니라, 관리자가 호출하는 기계적인 관문입니다.

1세션의 흐름

의뢰부터 보고까지의 흐름입니다. 각 태스크와 검증의 합격/불합격 분기 모두 관리자의 코드가 제어합니다.

승인 체인: 리뷰 너머의 다단계 관문

위의 기본 흐름에서는 「Reviewer」를 하나의 상자로 그렸지만, 실제로는 그곳이 여러 관문의 입구입니다. 각 단계는 이전 단계를 통과했을 때만 가동되며, 도중에 「수정 필요」가 발생하면 수정 라운드로 돌아갑니다.

(*)

이 붙은 단계는 조건부로, 기획서나 엔트리 HTML이 없는 세션에서는 건너뜁니다. 「README에 장을 추가하기」와 같은 요청이라면 Reviewer에서 완료되지만, 브라우저 게임을 만드는 요청이라면 마지막 화면 채점까지 진행되는 것처럼, 요청의 성질에 따라 관문의 수가 자동으로 변합니다. 각 단계의 수정 라운드에는 상한이 있으며, 상한을 다 써도 수렴하지 않으면 Analyst가 원인을 진단하여 1회에 한해 재정비를 시도합니다. 그래도 안 된다면 진단 결과를 리포트에 남기고 인간에게 인계합니다.

중요한 점은, 이러한 다단계화에서도 제어 흐름(Control Flow)의 형태는 변하지 않는다는 것입니다. 모든 단계는 「평가 → 수정 필요 시 Worker에게 수정을 시키고 재평가」라는 동일한 패턴을 따르며, 관리자(Manager) 코드가 순차적으로 호출할 뿐입니다. 단계를 추가하더라도 늘어나는 것은 검사 관점이지 제어의 복잡성이 아닙니다.

대응 방침의 상세

오케스트레이션 (Orchestration)을 LLM에 맡기지 않기

관리자 자체를 LLM으로 설정하여 태스크 할당, 진행 관리, 의존성 해결까지 맡기는 구성도 생각할 수 있습니다. 하지만 로컬 LLM은 상태를 정확히 추적하지 못해, 끝난 태스크를 재실행하거나 완료 조건을 무시하는 등 제어가 불안정해집니다.

따라서 진행을 결정하는 부분은 모두 결정론적인(Deterministic) 코드로 배치했습니다. 태스크의 순서, 재시도(Retry) 횟수, 수정 라운드의 상한, 언제 중단할 것인가—이것들은 모델의 판단이 아니라 코드의 상수와 분기로 결정됩니다. 관리자가 고정적으로 보유한 「정책(Policy)」을 정리하면 다음과 같습니다.

특히 효과적인 것은 검증의 합격 여부를 LLM의 자기 신고로 결정하지 않는 것입니다. Architect가 계획에 검증 커맨드(예: 테스트 실행)를 포함하고 있다면, 관리자가 이를 직접 실행하고 종료 코드(Exit Code)로 합격 여부를 판정합니다. 실제 환경에서 「테스트가 실패했는데도 Reviewer가 '승인'을 반환하는」 사례를 관찰했기 때문에, Reviewer 앞에 이 기계적인 관문을 두었습니다. 검증이 실패하고 있는 한, 수정 라운드를 다 써도 승인되지 않습니다.

대화가 아닌 「계약 (Contract)」으로 협조하기

다중 에이전트라고 하면 대화 로그를 공유하며 주고받는 설계를 떠올리기 쉽습니다. 하지만 로컬 LLM의 컨텍스트(Context)는 짧아서 전체 이력을 공유하면 금방 파탄 납니다. 그래서 에이전트 간의 직접적인 대화를 일절 없애고, 다음 에이전트에게 전달하는 것은 「설계 방침」과 「선행 태스크의 결과 요약(수백 자로 제한)」뿐입니다.

이는 생성하는 코드의 설계 원칙(인터페이스 우선, 느슨한 결합)을 팀 자체에 적용한 것입니다.

• Architect가 계약을 결정한다: 컴포넌트 간의 인터페이스나 엔드포인트를 명문화한다.
• Worker는 계약을 따른다: Backend와 Frontend는 서로의 구현을 보지 않고, 계약에만 의존하여 구현한다. 계약이 지켜지고 있다면 결합한다.
• QA는 계약을 검증한다: 테스트는 구현 내부가 아니라, 공개된 계약(API, 타입)에 대해 작성한다.
• Reviewer가 전체를 대조한다: 요청, 설계 방침, 차분(Diff)의 세 가지를 대조한다.

에이전트 간에 주고받는 「계약」은 모두 정해진 형태의 데이터입니다. 구현자를 위한 주요 계약 템플릿을 예로 들면 다음과 같습니다 (값은 설명을 위한 플레이스홀더입니다).

Architect의 출력(계획):

{
"architecture": "컴포넌트 간의 인터페이스 / 엔드포인트 설계 방침",
"verify": "빌드·테스트 검증 커맨드 (임의)",
...

Worker의 완료 보고 (finish_task 도구 호출. status는 done 또는 blocked):

{ "summary": "수행한 작업의 요약", "status": "done" }

Reviewer의 판정 (verdict는 approve 또는 request_changes):

{ "verdict": "request_changes", "summary": "총평",
"issues": [ { "file": "src/...", "comment": "구체적인 지적 사항" } ] }"

관리자는 받은 출력을 이 템플릿에 비추어 검증하며, 형식이 깨져 있다면 추출·재시도·폴백(Fallback)을 수행합니다. 프롬프트에 작성하는 스키마와 코드 측의 파서(Parser)는 항상 이 형태로 1대1을 유지합니다.

이 방식의 또 다른 장점은 역할을 늘려도 제어 흐름(Control Flow)이 늘어나지 않는다는 것입니다. Backend도 QA도 Designer도, 관리자 입장에서는 모두 동일한 Worker입니다. 차이점은 '합성되는 시스템 프롬프트(System Prompt)'와 '(설정이 있다면) 사용하는 모델'뿐입니다. 새로운 전문성은 역할별 프롬프트를 하나 작성하여 공통 규범에 연결하는 것만으로 추가할 수 있습니다. 컨텍스트 공유를 설계 단계부터 불가능하게 만들었기 때문에, 역할이 늘어나도 시스템이 무너지지 않습니다.

LLM의 출력을 믿지 않는다

프롬프트를 믿지 않고, 반드시 코드 측에서 추출·검증하며, 실패하면 폴백(Fallback)한다는 방침을 철저히 지키고 있습니다.

핵심은 어떤 실패 상황에서도 예외(Exception)를 던져 세션을 종료시키지 않는 것입니다. 예를 들어 계획 생성에 실패하면, 최종적으로는 '의뢰 전체를 하나의 태스크(Task)로 실행한다'는 방식으로 낮추어 처리합니다. Worker가 도구 호출(Tool Call)을 본문에 누락했다면, 본문에서 완료 보고를 찾아냅니다. 완료 보고가 없고 파일 변경도 없는 태스크는, 자기 보고가 '완료'라고 되어 있더라도 '미완료'로 취급합니다.

부작용은 코드의 게이트(Gate)에서 차단한다

에이전트가 가진 권한은 '도구를 호출하는 것'뿐이며, 실행 여부는 도구 내부(=코드)와 사용자가 결정합니다. LLM이 어떤 인자(Argument)를 생성하더라도 위험한 조작은 코드가 차단합니다. 승인은 3가지 상태—자동(읽기 전용) / 확인 / 거부(파괴적)—로 압축했습니다.

방어는 단층이 아닌 다층 구조입니다.

• 경로 봉쇄: 모든 파일 조작은 워크스페이스 내로 한정(../ 및 절대 경로 거부)
• 명령어 분류: 파괴적·권한 관련 명령어는 승인 프롬프트조차 띄우지 않고 거부. &&나 |로 연결된 명령어는 세그먼트별로 분류하여 최악의 값을 채택함으로써, 저위험 구간의 명령어를 통해 전체를 통과시키려는 우회로를 차단
• 기밀 파일 가드: 인증 정보나 비밀키는 읽기와 쓰기 모두 거부
• 외부 통신 차단: URL 취득은 프라이빗 IP(Private IP)를 확인한 후 차단(SSRF 방지)

자동 승인 모드를 사용하더라도 멈추는 것은 확인 프롬프트뿐이며, 이러한 코드 측의 방어 기제는 모두 살아 있습니다. 그리고 거부는 예외가 아니라 '거부되었습니다. 동일한 조작을 반복하지 마세요'라는 메시지로 모델에 반환합니다. 이는 로컬 LLM이 거부된 후에도 동일한 조작을 계속 재시도하는 실제 동작에 대한 대책으로, 방침을 바꾸거나 '차단됨'이라고 보고하도록 유도합니다.

에이전트의 도구: 도구(Tool)와 스킬(Skill)

에이전트의 능력은 성격이 다른 두 가지로 나누어 관리합니다. 이를 혼동하지 않는 것이 설계상의 핵심입니다.

• 도구(Tool) = '할 수 있는 일': 파일을 읽고, 쓰고, 명령어를 실행하는 등의 기계적인 능력. 부작용은 반드시 승인 게이트를 통과해야 함
• 스킬(Skill) = '방법': 특정 작업을 어떻게 진행할지에 대한 지식. Markdown으로 작성하며, 코드나 프롬프트 본체와 분리함

준비된 도구

도구를 가질 수 있는 것은 Worker뿐입니다(검사 단계는 읽기 전용 서브셋만 가집니다). 승인은 **자동(읽기 전용) / 확인 / 거부(파괴적)**의 3가지 상태이며, 판단은 프롬프트가 아닌 코드가 내립니다.

여기에 더해, 복잡한 태스크에서 작업 항목을 관리하는 todo 관리 도구(3단계 이상으로 생성하고 지워나가는 운용 방식)와, 설정 시 MCP 서버(기본적으로 Microsoft Learn 문서 검색) 도구가 Worker에게 부여됩니다. 웹 검색은 API 키를 설정했을 때만 활성화됩니다.

준비된 스킬

스킬은 '이 종류의 작업은 이렇게 진행한다'라는 규범을 적은 Markdown입니다.

Architect에게는 **카탈로그(이름과 설명만)**를 보여주고, 각 태스크(Task)에 필요한 스킬(Skill)을 선택하게 합니다. 관리자는 그 본문을 Worker의 입력에 주입합니다. 실행 시에 동적 검색은 하지 않으며, 존재하지 않는 스킬 이름은 무시합니다. 즉, 어디까지나 결정론적(Deterministic)으로 동작하게 합니다. 또한 auto

지정된 스킬(검증 계열 등)은 태스크의 역할이 일치하면 Architect의 할당에서 누락되더라도 자동으로 주입되어 폴백(Fallback)으로서 작동합니다.

동봉된 스킬은 다음과 같습니다. 대부분 실제 기기에서의 시행착오를 통해 얻은 지견을 절차로 코드화한 것입니다.

워크스페이스에 독자적인 스킬을 두면, 프로젝트 고유의 규약(명명 규칙, 테스트 명령 등)을 코드에 손대지 않고도 추가하거나 덮어쓸 수 있습니다. '지능에 의존하지 않는' 설계의 일환으로서, 흔히 발생하는 실패의 회피책을 모델의 기억이 아닌 외부의 절차서로서 보유하게 합니다.

보충: 컨텍스트(Context)를 자동으로 압축하기

도구(Tool) 간의 상호작용을 반복하면 과거의 도구 결과가 대화 이력을 압박합니다(긴 태스크의 경우 입력이 누적되어 수십만~수백만 토큰에 달합니다). 그래서 전송 전에 이력 크기를 개략적으로 계산하고, 예산을 초과하면 최근 몇 건을 제외한 오래된 도구 결과를 "생략되었습니다. 필요하다면 read_file로 다시 읽어주세요"라는 플레이스홀더(Placeholder)로 교체합니다.

지시나 판단의 문맥(시스템·사용자·어시스턴트의 발언)은 깎지 않고, 지우는 것은 도구 결과뿐입니다. 게다가 다시 읽을 수 있음을 명시함으로써, 정보를 잃은 채 모델이 폭주하는 것을 방지합니다. 짧은 컨텍스트와 긴 태스크를 양립시키기 위한 메커니즘입니다.

빠졌던 부분: 설계는 이론이 아니라 실제 기기의 실패로부터

이 설계의 상당 부분은 깔끔한 이론이 아니라, 실제 기기에서 관측한 실패를 하나씩 관문(Gate)으로 변환한 결과입니다.

이것들의 공통점은 '로컬 LLM의 선의를 믿지 않는다'는 한 점이었습니다.

동작 확인

기사의 내용이 탁상공론 설계로 끝나지 않았음을 보여주기 위해, 실제로 빌드·테스트·연결 확인·1세션 실행까지 마쳤습니다.

실제로 세션을 구동하기

격리된 임시 워크스페이스에서 "OVERVIEW.md를 만들어줘"라는 작은 의뢰를 자동 승인으로 실행했습니다. 본문에서 설명한 플로우(Flow)와 안전 메커니즘이 그대로 실제 기기에서 발화하는 것을 확인할 수 있었습니다.

• 설계: Architect(gpt-oss-20b)가 의뢰를 1개 태스크(Docs 역할)로 분해하고, 검증 명령까지 계획에 포함함
• 스킬의 자동 적용: 태스크의 역할이 docs였기 때문에, markdown-mermaid 스킬이 할당 지시 없이 자동으로 주입됨
• 구현: Worker가 write_file → edit_file → read_file로 자신의 성과물을 다시 읽어본 뒤 finish_task를 호출함
• doc-only 게이트: 변경 사항이 .md뿐이었기 때문에, 검증 명령은 자동으로 스킵됨(본문 "관문의 스킵"에서 언급한 동작이 실제로 작동함)
• 리뷰: Reviewer가 approve 하여, OVERVIEW.md가 지정된 내용대로 생성됨

이 세션의 통계는 LLM 호출 8회 / 도구 5회 / 입력 44,769·출력 4,473 토큰 / 소요 시간 약 1분 10초였습니다. 단순한 태스크라면 이 정도 규모와 시간으로 한 바퀴를 돕니다(복잡한 성과물의 경우, 이것이 여러 세션의 개선 루프가 됩니다).

요약

로컬 LLM을 전제로 한 에이전트 설계에서 효과적이었던 생각은 다음 3가지입니다.

• 지능에 의존하는 부분을 코드로 옮기기: 오케스트레이션 (Orchestration)·합격 여부 판정·안전성은 모두 결정론적인 (Deterministic) 코드가 담당하고, LLM에는 '설계·구현·지적'의 내용만을 맡깁니다.
• 대화가 아닌 계약(Contract)으로 연결하기: 컨텍스트 길이 (Context Length)의 제약과 궁합이 좋으며, 역할을 늘려도 제어 흐름 (Control Flow)이 비대해지지 않습니다.
• 설계를 실제 기기의 실패로부터 역산하기: 실제로 구동해보고 나서야 알 수 있는 실패에 맞춰 관문을 추가하는 것이, 이론을 앞세워 추상화 (Abstraction)를 늘리는 것보다 불필요한 복잡성을 떠안지 않는 방법입니다.

'모델이 똑똑해지면 불필요해질 고안'도 포함되어 있습니다만, 로컬 환경의 제한된 계산 자원 (Computing Resources)에서 구동하는 이상, 당분간은 이 '지능에 의존하지 않는 설계'가 현실적인 해답이라고 느끼고 있습니다.

마지막으로

설계의 대부분과 구현은 Fable 5에 /goal 명령어로 요청했습니다.

아쉽게도 더 이상 사용할 수 없게 되었지만, 비록 며칠간이었을지라도 Fable 5를 접해본 것은 귀중한 경험이었습니다.

Discussion