족쇄에서 닻으로: AI와 맞서지 않고 협업하는 법을 배워 버려진 오픈 소스 프레임워크를 부활시킨 방법

From Shackles to Anchors: How I Resurrected an Abandoned Open-Source Framework by Learning to Work With AI, Not Against It

GitHub Finish-Up-A-Thon 제출물

버려진 프레임워크

ReqForge는 오픈 소스 LLM 에이전트 하네스 (harness)입니다. 즉, 제품 아이디어를 배포 가능한 코드로 전환하기 위한 구조화된 워크플로 (workflow)입니다. 저는 몇 달 전에 이 프로젝트를 시작했습니다. 작동은 했지만, 무언가 잘못되어 있었습니다.

이 프레임워크는 단순한 철학을 바탕으로 구축되었습니다: 모델을 충분히 제약하면 올바른 코드를 생성할 것이다. 규칙 (Rules). 검증기 (Validators). 체크리스트 (Checklists). 게이트 (Gates). 모든 대화는 "하지 말아야 할 것"의 목록으로 시작되었습니다 — 과도한 추상화 금지, API 환각 (hallucinate) 금지, 빈 catch 블록 작성 금지, as any 사용 금지, 템플릿 복사 붙여넣기 금지 등...

저는 에너지의 대부분을 모델과 싸우는 데 사용하는 프레임워크를 만들었습니다. 결과는 예측 가능했습니다: 생성된 코드는 정확했지만 경직되어 있었습니다. 새로운 기능이 추가될 때마다 더 많은 규칙이 필요했습니다. 프레임워크는 점점 짐이 되어갔습니다.

저는 프로젝트를 보류했습니다.

불꽃

그러던 중 저는 2300년 된 중국 철학 텍스트에 관한 YouTube 영상을 보게 되었습니다. 바로 칼날이 결코 무뎌지지 않는 백정, 포정(Cook Ding)의 이야기입니다.

문혜군(Lord Wenhui)은 포정이 소를 해체하는 모습을 지켜봅니다. 다른 백정들은 뼈를 부수며 작업하고 매달 칼을 교체합니다. 하지만 포정의 칼날은 음악처럼 소의 몸을 미끄러지듯 통과합니다. 수천 마리의 소를 해체한 후에도 그의 칼은 여전히 날카롭습니다.

"어떻게 된 일인가?" 군이 묻습니다.

포정이 대답합니다: "제가 관심을 두는 것은 기술을 넘어선 도(Way)입니다. 훌륭한 백정은 매년 칼을 바꿉니다. 평범한 백정은 매달 칼을 바꿉니다. 저는 이 칼을 19년 동안 사용했습니다. 처음 시작했을 때는 소 전체밖에 보이지 않았습니다. 3년이 지나자 더 이상 소가 보이지 않았습니다 — 관절 사이의 틈이 보였습니다. 이제 저는 눈이 아닌 정신으로 소를 마주합니다. 감각은 멈추고, 나의 정신이 칼을 인도합니다."

저는 깨달았습니다: 제 프레임워크는 "훌륭한 백정" 수준에 머물러 있었다는 것을요. 저는 틈새를 보는 법을 배우는 대신, 더 나은 규칙, 더 날카로운 검증기, 더 많은 게이트 — 즉, 더 좋은 칼 — 를 추가하고 있었던 것입니다.

그 간극은 모델의 자연스러운 패턴 매칭 (pattern-matching) 능력입니다. LLM은 논리 엔진 (logic engines)이 아닙니다. 이들은 패턴 매처 (pattern matchers)입니다. 모든 "하지 마시오"라는 규칙은 모델이 자신의 자연스러운 생성 패턴을 억제하도록 강제합니다. 이와 싸우는 대신, 저는 모델과 함께 작업해야 했습니다.

부활: 족쇄에서 닻으로

저는 저장소 (repo)를 다시 열고 설계 철학을 완전히 새로 작성했습니다.

이전 (족쇄)

프레임워크의 코드 생성 가이드는 다음과 같았습니다:

체크리스트:
- [ ] 과도한 추상화 금지
- [ ] 환각된 API (hallucinated APIs) 금지
...

9개의 "하지 마시오" 규칙이 있었습니다. 모델은 코드를 생성하는 동시에 자신의 자연스러운 성향을 억제하며 이 규칙들을 암송해야 했습니다. 모든 억제 시도는 실패할 수 있었습니다.

이후 (닻)

저는 체크리스트를 모델에게 무엇을 '해야 하는지' 보여주는 완벽한 패턴인 세 가지 짧은 코드 예제로 교체했습니다:

// 닻 1: 에러 핸들링 패턴
async function createUser(email: string, password: string): Promise<User> {
  const existing = await db.user.findUnique({ where: { email } });
...

(여기에 API 엔드포인트 및 테스트 패턴 닻이 추가되었습니다.)

모델은 세 가지 완벽한 예시를 읽고, 패턴 매칭 (pattern-matching) 기능이 활성화되어 자연스럽게 올바른 스타일로 생성을 이어갑니다. 체크리스트는 생성 가이드에서 배포 전 무결성 검사 (sanity check)로 격하되어 안전망 역할만 수행합니다.

전체적인 변화

저는 GitHub Copilot과 함께 한 번의 연속된 세션 동안 8가지의 상호 연결된 변경 사항을 적용했습니다:

변경 사항	이전	이후
난이도 표시 (Difficulty markers)	모든 작업을 동일하게 취급	🔴/🟡/🟢 레벨 — 어려운 작업에서는 모델이 속도를 늦추고, 쉬운 작업은 빠르게 통과
...

또한 이 접근 방식이 작동함을 증명하기 위해 **벤치마크 (benchmark)**를 작성했습니다 — 동일한 작업, 두 가지 접근 방식, 측정된 결과:

차원 (Dimension)	기존 (9개 규칙)	신규 (3개 닻)
통과된 테스트	26/26	26/26
...

그리고 철학을 설명하는 **선언문 (manifesto)**도 작성했습니다 — From Shackles to Anchors.

GitHub Copilot이 이를 어떻게 가능하게 했는가

이것은 단순히 "1,000줄의 보일러플레이트 (boilerplate) 코드를 작성하는" 세션이 아니었습니다. 훨씬 더 흥미로운 과정이었습니다.

가장 가치 있었던 Copilot과의 상호작용은 코드 완성 (code completion)이 아니라, 설계 철학 (design philosophy)에 대한 토론이었습니다. 저는 장자 (Zhuangzi)에 관한 중국어 자막 파일을 대화창에 붙여넣었습니다. Copilot은 이를 LLM 하네스 (harness) 설계와 연결했습니다. 우리는 "2.5 레이어" 개념을 함께 반복적으로 개선해 나갔습니다. 이는 주인과 도구의 관계가 아니라, 아이디어를 정교화하는 두 명의 협업자로서의 과정이었습니다.

Copilot은 단순히 코드를 생성하기만 한 것이 아니었습니다. Copilot은 다음과 같은 역할을 수행했습니다:

나의 가설에 도전함 — 제가 더 많은 규칙을 추가하자고 제안했을 때, Copilot은 제가 "좋은 정육점 칼"을 만들고 있는 중이라고 지적했습니다.
이질적인 아이디어들을 연결함 — 장자의 정육점 기술 🠒 Transformer 패턴 매칭 (pattern matching) 🠒 앵커 기반 가이드 (anchor-based guidance)
코드 변경 사항을 생성함 — 단 한 번의 연속된 세션 동안 프레임워크의 8가지 수정 사항을 모두 구현했습니다.
벤치마크 (benchmark)를 작성함 — 재현 가능한 비교 테스트를 생성했습니다.
철학 문서를 초안함 — 중국어 통찰을 영어로 번역했습니다.

최종 프레임워크는 4개의 AI 클라이언트 어댑터 (client adapters) 전반에 걸쳐 236개의 파일이 동기화되어 있으며, 98개의 유닛 테스트 (unit tests)가 모두 통과되었고, 생성된 코드는 측정 가능한 수준으로 더 깔끔해졌습니다. 하지만 진정한 변화는 설계 철학에 있었습니다.

결과

이 프로젝트는 버려진 규칙 수집 모음에서 다음과 같은 특징을 가진 일관되고 철학 중심적인 프레임워크로 거듭났습니다:

4개의 AI 클라이언트 어댑터 (Claude Code, Cursor, OpenCode, Gemini CLI)
앵커 기반 가이드를 갖춘 13개의 스킬 (skills)
특화된 작업을 위한 10개의 서브 에이전트 (sub-agents)
forge-scaffold init을 위한 4개의 프로젝트 스타터 템플릿
모든 어댑터에 완벽하게 동기화된 944개의 파일
모두 통과된 98개의 유닛 테스트
벤치마크 증거를 포함하여 발표된 설계 선언문 (design manifesto)
철학을 설명하는 GitHub Issue

더 중요한 것은, 이 프레임워크가 더 이상 모델과 싸우지 않는다는 점입니다. 모델과 함께 작동합니다.

링크

Repository: github.com/zxpmail/ReqForge
Design Manifesto: Issue #1
Benchmark Data: benchmark/
Benchmark Technical Post: docs/benchmark-technical-post.md

GitHub Copilot을 사용하여, 버려진 저장소(repo)에서 출판된 디자인 철학에 이르기까지 — 이 모든 과정을 단 한 번의 연속된 세션으로 구축하였습니다.