거대 프레임워크를 AI와 만들며 깨달은, 개발 철학을 '명문화'하는 기술

「방금 전까지는

Result

로 반환하더니, 이번에는 panic으로 떨어뜨리네.」

「어제는 이런 방식으로 작성했는데, 오늘은 다른 스타일로 써오네.」

AI에게 코드를 작성하게 하면서, 이런 느낌을 받은 적이 없으신가요?

저는 있습니다.

Claude Code는 개별적인 diff(차이점)만 보면 우수합니다. 하지만 방치해 두면 프로젝트 전체로서의 일관성은 아무렇지 않게 무너져 버립니다.

왜일까요?

답은 간단합니다. AI가 "우리 프로젝트는 이렇게 작성한다"라는 전제를 모르기 때문입니다.

저는 지난 반년 동안 Claude Code와 함께 Rust로 제작된 풀스택 Web 프레임워크인 Reinhardt를 만들어 왔습니다.

크레이트(Crate) 수는 30개를 넘었고, 코드 라인 수는 70만 행 규모가 되었습니다.

이 정도 규모를 AI와 함께 만들며 제가 도달한 결론은 다음과 같습니다.

AI에게 일관된 판단을 내리게 하고 싶다면, 머릿속에 있는 설계 철학을 외부로 써 내려갈 수밖에 없다.

오늘은 그 "써 내려가는" 행위——제가 **Philosophy-Driven Development (철학 주도 개발)**라고 부르는 것——를 Reinhardt의 실제 파일을 보여드리며 솔직하게 작성하겠습니다.

1. 왜 '명문화'인가 — 암묵지는 AI에게 전달할 수 없다

인간 팀에게는 암묵지(Tacit Knowledge)가 통합니다.

선배가 작성한 코드를 보고, 리뷰에서 지적받고, 회식 자리에서 푸념을 들으며 "아, 우리 팀은 이런 설계를 싫어하는구나"라고 몸소 익혀갑니다.

명문화되어 있지 않더라도, 분위기로 전달되는 부분은 분명히 존재합니다.

하지만 AI 에이전트에게는 등을 보여줄 대상이 없습니다.

세션(Session)이 바뀌면 기억은 리셋되고, 매번 완전히 새로운 신입 사원처럼 나타납니다.

선배의 뒷모습도, 과거의 리뷰도, 회식 자리의 푸념도 그 무엇 하나 이어받지 못합니다.

즉, 써 내려가지 않은 "우리만의 방식"은 AI에게 존재하지 않는 것과 같습니다.

여기서 이전에 기사에서도 썼던 Claude Code의 정체를 떠올려 보십시오.

Claude Code는 개발자가 아니라, 증폭기입니다.

좋은 전제를 주면 좋은 코드를 대량으로 내놓고, 모호한 전제를 주면 모호한 코드를 대량으로 내놓습니다.

빨라지는 것은 성공뿐만이 아닙니다. 실패 또한 같은 속도로 증가합니다.

따라서 증폭되기 전의 입력값——설계 철학——을 모호한 상태로 방치하면, 모호함이 스케일(Scale)합니다.

증폭기에게 필요한 것은 북극성입니다.

어디로 향해야 하는지를 보여주는, 흔들리지 않는 단 하나의 점.

그것을 인간의 머릿속에만 둔 채로 두지 않고, 파일로서 외부로 꺼내는 것. 이것이 명문화의 출발점입니다.

2. reinhardt의 '헌법'은 고작 1.4 KB뿐이다

"설계 철학을 명문화하라"라고 하면, 두꺼운 스타일 가이드(Style Guide)를 상상할지도 모릅니다.

하지만 Reinhardt의 철학을 정한 파일은 고작 1.4 KB입니다.

instructions/DESIGN_PHILOSOPHY.md에는 10개의 원칙이 불렛 포인트로 나열되어 있을 뿐입니다.

그중 일부를 발췌하겠습니다.

# Reinhardt Design Philosophy
These principles guide ALL design decisions in the Reinhardt framework.
1. **Magic must be understandable** — Every convention must be a trick the user can see through; no opaque magic
...

주목해야 할 점은, 추상론으로 끝나지 않았다는 부분입니다.

원칙 2번 "규약은 도메인 지식 없이도 예측 가능해야 한다"에는 바로 아래에 구체적인 예시가 붙어 있습니다.

Person의 복수형을 People로 만드는 것은 영어의 복수형 지식을 요구하기 때문에 안 됩니다. PersonSettings라면 누구나 기계적으로 예측할 수 있으므로 좋습니다.

이 "좋은 예·나쁜 예"가 한 줄 덧붙여져 있는 것만으로도, 철학은 갑자기 운용 가능한 것이 됩니다.

AI에게 "예측 가능하게 해줘"라고 말해도 전달되지 않지만, "People이 아니라 PersonSettings처럼"이라고 말하면 단번에 전달됩니다.

그리고 짧다는 것에는 의미가 있습니다.

1.4 KB이기 때문에 에이전트는 매 세션마다 전체 내용을 다시 읽을 수 있습니다.

50페이지짜리 스타일 가이드는 인간도 AI도 결국 읽지 않습니다.

철학은 다시 읽힐 수 있는 길이로 유지될 때 비로소 기능합니다.

@로 매번 읽히기

적기만 해서는 아무도 읽지 않는다 — 이것이 명문화(Documentation)의 가장 큰 함정입니다.

훌륭한 PHILOSOPHY.md를 작성하더라도, docs/ 깊숙한 곳에서 누구에게도 열리지 않은 채 썩어갑니다.

당신의 회사의 docs/ 안에도 그런 "읽히지 않는 정론"이 잠들어 있지 않나요?

Reinhardt는 이를 @ 참조라는 수수한 장치로 해결합니다.

에이전트(Agent)를 위한 지시서인 CLAUDE.md와 AGENTS.md 모두, 17행에 이 한 줄이 있습니다.

@instructions/DESIGN_PHILOSOPHY.md

이 @instructions/DESIGN_PHILOSOPHY.md는 파일을 지시서 본문에 **인라인 전개(Inline expansion)**하는 참조입니다.

Claude Code는 이 지시서를 읽어들일 때마다, 철학 파일의 내용을 반드시 함께 읽습니다.

즉, 에이전트는 매 세션, 작업을 시작하기 전에 헌법을 다시 읽고 나서 움직입니다.

인간보다 더 성실합니다.

저는 제 회사의 행동 지침을 매일 아침 다시 읽지는 않지만, 에이전트는 불평도 없이 매번 읽습니다.

명문화의 가치는 작성한 순간이 아니라, 참조된 순간에 생겨납니다.

그리고 AI 주도 개발(AI-driven development)에서는 이 "참조"를 시스템으로서 자동화할 수 있습니다. 이 점이 인간만의 개발과 결정적으로 다른 부분입니다.

4. 원칙은 규약(Convention)으로 번역되어야 비로소 지켜질 수 있다

그렇다고는 해도, "Fail early(빨리 실패하라)"라는 원칙만으로는 아직 너무 추상적입니다.

구체적으로 어떤 코드를 어떻게 작성해야 "빨리 실패"한 것이 되는가. 그 부분을 채우지 않으면 철학은 염불(공허한 외침)로 끝납니다.

Reinhardt에서는 철학이 하위 규약 문서로 **카스케이드(Cascade)**됩니다.

DESIGN_PHILOSOPHY.md를 정점으로 ANTI_PATTERNS.md, TESTING_STANDARDS.md, MACRO_USAGE.md와 같은 구체적인 규약으로 가지가 뻗어 나갑니다.

흥미로운 점은, 가지 쪽에서 원칙 번호를 명기하여 역참조(Back-reference)하고 있다는 것입니다.

예를 들어 매크로 설계 규약인 MACRO_USAGE.md에는 다음과 같은 줄들이 나열됩니다.

- DESIGN_PHILOSOPHY #5 ("API ergonomics is paramount"): named setters scale
- DESIGN_PHILOSOPHY #9 ("Every framework eventually becomes outdated"):
- DESIGN_PHILOSOPHY #4 ("Fail early"): the per-field type-state lifts

이 #5, #9, #4가 핵심입니다.

"왜 이 매크로는 이런 설계인가?"라고 물었을 때, 규약에서 원칙으로 번호 하나만으로 거슬러 올라갈 수 있습니다.

규약이 일방적으로 내려오는 것이 아니라, 반드시 WHY(이유)에 연결되어 있습니다.

이것이 Philosophy-Driven Development의 핵심입니다.

규칙에는 그것이 존재하는 이유가 있습니다.

이유가 철학에 묶여 있기 때문에, 새로운 상황에 맞닥뜨려도 "원칙에 비추어 보면 이럴 것이다"라고 판단을 확장할 수 있습니다.

AI도 인간도 암기가 아닌 원칙으로부터 연역(Deduction)할 수 있게 됩니다.

5. 마지막은 기계가 지키게 한다

그럼에도 인간은 잊어버립니다. AI도 잊어버립니다.

철학을 읽게 하고 규약으로 번역해도, 마지막의 마지막 순간에 "뭐 이번에는 괜찮겠지" 하는 상황이 발생합니다.

그래서 Reinhardt는 원칙을 기계가 검사할 수 있는 형태까지 내려보냅니다.

"Fail early"를 예로 들어보겠습니다.

해결되지 않은 todo!()나 unimplemented!(), 지우는 것을 잊은 dbg!()는 "실패를 뒤로 미룬 코드"입니다. 원칙 4번에 정면으로 반합니다.

이를 탐지하는 태스크(Task)가 로컬의 Makefile.toml에 정의되어 있습니다.

[tasks.clippy-todo-check]
description = "Check for development-only code (todo!, unimplemented!, dbg!)"

그리고 동일한 체크가 CI 워크플로우인 todo-check.yml로서 실행되어, 새로운 todo!()를 포함하는 Pull Request를 차단합니다.

원칙 9번 「프레임워크는 언젠가 낡는다」를 지키기 위한 semver-check.yml

마찬가지로, 호환성을 깨뜨리는 변경을 기계적으로 차단합니다.

이 단계까지 오면, 카스케이드(Cascade)는 4단계가 됩니다.

DESIGN_PHILOSOPHY #4（Fail early）
└→ TESTING_STANDARDS.md / ANTI_PATTERNS.md（규약으로 번역）
└→ Makefile.toml: clippy-todo-check（개발자의 로컬 환경에서 검사）
...

가장 아래 단계까지 내려가면, 철학은 '사람의 선의'가 아니라 '머지(Merge)할 수 있는지 여부'가 됩니다.

선의는 흔들립니다. 오늘은 지킬 수 있어도, 마감 전날 밤에는 무너집니다.

하지만 CI 게이트는 흔들리지 않습니다. AI가 아무리 빠르게 코드를 뱉어내더라도, 게이트는 동일한 속도로 앞을 가로막습니다.

증폭기의 폭주를 마지막에 받아내는 것은, 기계화된 철학입니다.

6. 명문화가 효과를 발휘하는 것은 AI 상대뿐만이 아니다

지금까지 'AI를 위해 작성한다'는 이야기를 해왔습니다.

하지만 명문화된 철학이 지키는 것은 AI뿐만이 아닙니다.

가장 도움이 되는 것은, 6개월 뒤의 자신입니다.

저는 제가 왜 그런 설계를 선택했는지 아주 쉽게 잊어버립니다.

"여기, 왜 이렇게 우회적인 방식으로 작성했었지?"라며 과거의 자신을 추궁하고 싶어지는 밤이 몇 번이고 있었습니다.

원칙 번호가 붙은 철학이 있다면, 그 밤에 답이 돌아옵니다. "아, #4를 지키기 위해서였구나"라고 말이죠.

그리고 이것은, 이전에 「코드는 읽어야 하는가?」라는 기사에서 썼던 이야기와 맥락이 이어집니다.

그 기사에서 저는, 설계만큼은 에이전트(Agent)에게 통째로 맡겨서는 안 된다고 썼습니다.

설계를 자신이 쥐고 있다면, 생성된 코드를 대충 훑어보더라도 어디를 봐야 할지 알 수 있습니다. 쥐고 있지 않다면, 모든 행을 다 읽어도 아무것도 알 수 없게 됩니다.

명문화된 개발 철학은, 바로 **「설계를 계속 쥐고 있기 위한 장치」**입니다.

철학을 파일로 고정해 두면, 설계의 주도권은 인간 측에 남습니다.

AI는 그 철학의 안쪽에서 고속으로 코드를 늘려갑니다.

철학을 써두지 않은 채 AI에게 맡기면, 설계의 주도권은 어느샌가 누구의 손에도 남지 않게 됩니다.

7. 결론: 철학을 써라, 그리고 기계가 지키게 하라

처음의 위화감으로 돌아가 보겠습니다.

"방금 전에는 Result로 반환하더니, 이번에는 panic으로 떨어뜨리네"

6개월 동안 AI와 거대한 것을 만들어보며, 저는 이것을 AI의 결함이라고 생각하지 않게 되었습니다.

북극성(North Star)을 전달하지 않은 제 쪽의 결함입니다.

증폭기에 방향을 주지 않으면, 증폭기는 모든 방향으로 출력을 내보냅니다.

단지 그뿐이었습니다.

그래서 저는 개발 철학을 다음 순서로 다루려고 노력합니다.

쓰기: 머릿속의 "우리 방식은 이렇다"를 10줄이라도 좋으니 파일로 만든다.
읽히기: @ 참조를 통해 에이전트가 매 세션마다 읽어들이게 한다.
번역하기: 원칙을 번호로 역참조할 수 있는 구체적인 규약으로 떨어뜨린다.
지키게 하기: 규약을 CI가 검사할 수 있는 기계적인 게이트까지 내린다.

이 4단계를 거치면, 철학은 '훌륭한 시(Poem)'에서 '머지 가능 여부'로 모습을 바꿉니다.

그리고 AI 주도 개발(AI-driven development)은 빠를 뿐만 아니라, 흔들리지 않는 것이 됩니다.

마지막으로, 당신에게 묻겠습니다.

당신의 프로젝트의 "우리 방식은 이렇다"는 지금 누군가의 머릿속에만 머물러 있지 않습니까?

그것을 1.4 KB의 파일로 써 내려가는 것만으로도, AI도, 미래의 당신도 길을 잃지 않게 됩니다.

완벽한 철학일 필요는 없습니다.

우선 10줄, 써보시기 바랍니다. 북극성은 쓰는 순간부터 빛나기 시작합니다.