v1.0 Design 원칙 7가지 — 모든 결정의 기반

Architecture를 그리기 전에 원칙을 정한다. 모든 후속 design 결정은 이 7가지를 어기지 않아야 함. Matt가 호출한 3권 + 12% production pattern + 5 기둥에서 압축. Strategic level의 사고 도구.

한 줄

원칙은 architecture를 만드는 도구가 아니라, 수많은 결정을 내릴 때 매번 돌아오는 기준점. 7개로 압축해두면 매 결정마다 5 기둥·12% pattern·Matt thesis를 다시 풀어볼 필요가 없음.

원칙의 source

3권은 시간이 검증한 원리. 12% pattern은 시장이 검증한 운영 프로필. 둘이 만나는 자리가 v1.0의 design 원칙.

원칙 7가지 — 한 그림

원칙 1 — Deep Modules over Shallow

정의: 작은 interface, 깊은 implementation. 사용자가 보는 표면은 좁고, 그 뒤의 동작은 풍부.

출처: Ousterhout — A Philosophy of Software Design. 책 전체에서 가장 자주 호출되는 원칙.

왜: shallow module은 사용자가 내부 동작까지 알아야 쓸 수 있음. 그러면 모듈 경계가 무의미해지고 사용자의 strategic 사고 공간이 좁아짐 (Matt thesis와 직접 만남).

v1.0 적용 사례:

• v0.1 Provider trait는 method 4개 (stream, complete, name, model_config). 그 안에 vendor별 quirk·retry·cache가 들어 있음
• SKILL.md frontmatter는 5-7 field. 그 안에 lazy loading·context budget·tool whitelist가 처리됨
• agent loop crate는 run(prompt) -> Result. 안에 turn·tool dispatch·context compaction

어기면: Goose가 시간이 지나며 trait가 두꺼워진 것. 사용자가 모든 method를 이해해야 함 → strategic 사고 X.

원칙 2 — Strategic Substrate, Tactical Execution

정의: harness는 사람의 strategic 결정 표면만 노출. tactical 동작은 안에서 처리.

출처: Matt thesis 직접 호출 + Ousterhout의 strategic vs tactical programming (책의 별 챕터).

왜: AI 시대에 사람이 노릴 자리는 낮은 곳이 아니라 높은 곳. v1.0은 사람을 strategic level에 머물게 하는 substrate.

v1.0 적용 사례:

• 사람: 어떤 skill을 만들지, 어디서 confirm 받을지, 어떤 success criteria를 줄지
• AI: 실제 click·input·parse·refactor·test
• v0.6 hooks layer = 사람의 strategic 결정을 lifecycle event에 박는 mechanism
• v0.5 SKILL.md = 사람의 strategic 결정을 declarative spec으로 표현

어기면: vibe coding처럼 사람이 spec만 던지고 AI가 architecture까지 결정 → 1차 ok, 2차 worse, 3차 garbage.

원칙 3 — Ubiquitous Language per Segment

정의: 도메인 vocabulary와 코드/agent의 vocabulary가 같은 언어. segment마다 자기 vocabulary.

출처: Evans — DDD 핵심. + Matt가 강연에서 "ubiquitous language skill" 호출.

왜: AI가 도메인 vocabulary로 사고하지 못하면 추상화 leak. 학내 사용자가 "수강신청"이라고 하는데 agent가 "course registration form submission"으로 이해하면 매번 번역 비용.

v1.0 적용 사례:

• 학내 segment용 ubiquitous language skill: 학번, 학과 코드, 과목 코드, 학사 일정, 학식, 동아리
• v0.5 skill layer가 segment vocabulary를 정식 채택
• AGENTS.md는 도메인 용어집을 처음 부분에 박음
• 학내 통합 모듈은 학내 용어 그대로 API 설계

어기면: 일반화된 vocabulary로 통합 → 학내 사용자가 자기 작업을 번역해야 함. 진입 장벽이 사실상 늘어남.

원칙 4 — Orthogonal Layers, Reversible Decisions

정의: 각 layer의 변화가 다른 layer에 영향 안 줌. 가능한 한 모든 결정을 되돌릴 수 있는 형태로.

출처: Pragmatic Programmer — Orthogonality와 Reversibility가 책의 핵심 두 원칙.

왜:

• Orthogonality: layer가 얽히면 한 변경이 여기저기 깨짐. 학내 segment 변경이 v0.1 trait를 흔들면 안 됨
• Reversibility: 산업이 변할 때 vendor 갈아끼우기, protocol 바꾸기가 가능해야 함. lock-in 회피

v1.0 적용 사례:

• crate 단방향 의존 (llm-core ← llm-providers ← llm-loop ← my-cli). 역방향 X
• vendor 결정은 adapter crate에 격리. core trait는 변경 X
• ACP를 외부 인터페이스로 → 내부 구현 변경이 client에 안 보임
• skill 정의는 declarative — 코드가 아니라 spec이라 갈아끼우기 쉬움

어기면: Claude Code/Codex의 vendor 모델 갈아끼우면 prompt/tool 다 흔들림. v1.0은 처음부터 회피.

원칙 5 — Named Ownership + Scoped Success Criteria

정의: 모든 agent·skill·tool에 책임자와 성공 기준이 명시적으로 박혀 있음.

출처: 12% production 도달 패턴 1+2 (March 2026 enterprise survey).

왜: 익명 swarm은 brittle, expensive, debug 불가. 책임자가 없으면 누가 고칠지 모름. 성공 기준이 없으면 언제 멈출지 모름 (Ralph Loop의 verify function이 이 자리).

v1.0 적용 사례:

• SKILL.md frontmatter에 owner, success_criteria field 처음부터
• agent run에 for: <task>, done_when: <condition> 명시
• 학내 marketplace에 올라가는 skill은 owner가 학번/조직/팀. 익명 X
• Ralph Loop 패턴 그대로: verify_completion 함수가 success criteria

어기면: 누가 책임지는지 모름 → fail 시 고칠 사람이 없음. 성공 기준 없음 → agent가 무한 loop 또는 조기 종료 (context anxiety).

원칙 6 — Ship-and-Roll-Back as Normal Operation

정의: 배포와 롤백이 둘 다 verdict가 아닌 normal operation. 둘 중 하나로 해석하지 않음.

출처: 12% production 도달 패턴 4 + 사용자 아이디어 2 (sandbox + rollback) + Pragmatic Programmer의 Reversibility.

왜: 88% pilot이 못 가는 이유 중 큰 것이 roll-back을 실패로 해석하는 조직 문화. 12% 성공 cohort는 둘 다 normal로 봄. v1.0은 이걸 mechanism으로 박아서 사용자가 문화적 부담 없이 둘 다 사용.

v1.0 적용 사례:

• v0.8 sandbox + filesystem snapshot rollback (자동)
• 외부 effect는 approval gate (사전 차단)
• skill은 git commit 단위로 ship, git revert 단위로 rollback
• 학내 marketplace는 skill version + rollback metadata 표시

어기면: 사용자가 ship을 두려워함 → pilot에 머무름 → 88% cohort 합류.

원칙 7 — Anti-Corruption Layer for Every External

정의: 외부 시스템(vendor LLM, MCP server, 학내 API)과의 경계마다 anti-corruption layer. 외부 변화가 내부 모델을 오염시키지 않게.

출처: Evans — DDD의 anti-corruption layer 패턴.

왜:

• vendor LLM: API spec 변경 (OpenAI는 자주, Anthropic도 가끔). 내부 코드 100군데 안 바꾸려면 adapter
• MCP server: protocol 변경 가능. ACL이 변경 흡수
• 학내 시스템: 학사 일정·시스템 개편 빈번. 내부 도메인 모델은 학내 도메인 그 자체, 외부 시스템 형식은 ACL에서 변환

v1.0 적용 사례:

• llm-providers-openai crate는 외부 OpenAI API의 anti-corruption layer. 내부 Provider trait가 안정
• 학내 시스템 통합 모듈은 학내 시스템 API → 학내 도메인 모델 변환 layer
• MCP bridge crate는 MCP protocol → tool spec 변환

어기면: 외부 변화가 내부에 직접 침투 → vendor가 spec 바꿀 때마다 agent loop까지 깨짐.

원칙 간 trade-off / 충돌 해결

7개 원칙이 충돌하는 경우가 있음. 충돌 시 우선순위:

→ 7개 원칙은 대체로 강화. 충돌은 표면적인 경우가 많음.

결정 순서 — 매 design 결정마다

새 기능·layer·결정을 마주칠 때 이 순서로 원칙 적용:

→ 7개 모두 통과해야 design 결정 채택. 매 결정마다 이 트리를 머릿속에 통과.

다음 단계 — 이 원칙으로 무엇을 그릴 것인가

7가지 원칙이 정해졌으니, 다음 후속 design 노트들이 자연스럽게 따라옴:

각 노트는 이 원칙들을 어떻게 구체화할지가 주제. 코드가 아니라 추상적 design.

인사이트 — 원칙이 v1.0의 self-test가 됨

이 7가지 원칙의 가장 큰 가치는 결정의 도구가 아니라 회고의 도구:

• v0.x 단계가 진행되면서 design이 표류할 때 → 이 7개로 self-test
• 새 사용자가 v1.0 contributing할 때 → 이 7개를 알면 방향 정렬
• 학내 사용자가 자기 skill 만들 때 → 7개를 guideline으로 제공 → 자기 도구가 v1.0과 정합

→ 원칙은 중력. 모든 결정이 자연스럽게 같은 방향을 가리킴.

관련

• software-fundamentals-thesis — Matt thesis (원칙 2의 직접 출처)
• industry-hot-issues-2026 — 시장 컨센서스 (원칙들의 사후 검증)
• research-to-production-gap — 12% pattern (원칙 5, 6의 출처)
• stateless-definition — v0.1 (원칙 1, 4 적용 사례)

Sources

• A Philosophy of Software Design — John Ousterhout (Stanford)
• The Pragmatic Programmer — Hunt & Thomas
• Domain-Driven Design — Eric Evans
• Matt Pocock — Software Fundamentals Matter More Than Ever
• vault 내부: 5 기둥 + 12% pattern 모든 노트