Interface as Strategic Surface — 14 원칙 통합 운영 답
사용자가 14 원칙을 다 흡수한 후 도달한 통찰: simplex 구조를 strategic하게 설계 = interface 정의 + reversible 방향 — 정확하고 14 원칙의 통합 운영 답. synthesis-complex-to-simple(theory) · student-application-guide(timeline) · adr-as-strategic-mechanism(mechanism)에 이은 응용 4번째 노트. interface가 무엇이고 어떻게 만드는가가 14 원칙 학습의 진짜 종착점.
한 줄
Interface = 사용자(인간 or AI)의 mental model에 맞춰 변할 수 있는 것을 감추고 약속을 명시하는 표면. 단순히 함수 signature가 아니라 약속의 형식. *사람이 strategic 시간을 쏟는 자리가 거의 interface 정의 + 재정의이고, 14 원칙 모두가 interface design의 다른 면. Reversibility를 default로 두면 interface는 살아있는 도구가 됨.
⚛️ 철학 — Interface가 strategic 사고의 결정체
영어 어원: inter (사이) + face (얼굴) = 경계의 표면. 즉 두 entity 사이의 약속.
CS 단위별:
- Module level — 함수 signature, class public method
- Component level — trait, protocol, interface keyword
- Service level — API spec (REST, gRPC, GraphQL)
- Human level — AGENTS.md, SKILL.md, ADR
이 모든 level에서 interface = "약속의 형식". 약속에 들어가는 것:
| 요소 | 답하는 질문 |
|---|---|
| What | 어떤 동작을 보장하는가 |
| When | 어떤 조건에서 작동하는가 |
| What not | 무엇을 안 하는가 — leak / side effect / failure mode |
| Compatibility | 언제·어떻게 변할 수 있는가 |
좋은 interface = *사용자가 내부 모르고도 자기 일을 끝낼 수 있는 contract. 안 끝나면 internal에 의존 시작 → 추상화 깨짐 (Spolsky's Law).
Strategic 사고와의 직접 만남
strategic-vs-tactical-programming 명제 다시: strategic = 시스템 design을 좋게 만드는 시간. 이 시간이 구체적으로 무엇을 하는가의 답:
Strategic 시간 ≈ Interface 정의 + 재정의 + leak 인지 + 진화 결정
코드를 짜는 그 시간 자체는 tactical (AI 위임 OK). Strategic 시간이란 interface 표면을 깎고 다듬는 시간. 이게 사용자가 도달한 통찰의 가장 깊은 표현.
🔍 Interface 만들 때 매번 묻는 4가지 질문
1. 무엇을 감출 것인가?
information-hiding 명제 직접 적용:
- 무엇이 변할 수 있는가?
- 변하는 것을 감춤
Secret 후보 (Parnas 분류):
- Vendor (OpenAI vs Anthropic)
- Algorithm (quicksort vs mergesort)
- Schema (JSON vs Protobuf)
- Persistence (filesystem vs DB vs S3)
- Concurrency model (thread vs async)
- Time (UTC vs local)
→ 변할 가능성이 있는 모든 결정이 secret 후보. 어떤 결정을 secret으로 만들지가 interface 정의의 가장 strategic한 결정.
2. 무엇을 노출할 것인가?
Public surface — 사용자가 반드시 알아야 하는 것:
- 잘못 알면 시스템이 고장 — 명시적 contract로
- 사용자가 내부에 손 안 대고 자기 일을 끝낼 수 있어야
표면 작게 유지: deep-modules 정신 — 작은 interface, 풍부한 implementation.
3. 무엇이 leak하는가?
information-leak-vs-abstraction 명제 — Spolsky's Law:
모든 non-trivial abstraction은 어느 정도 leak한다
Leak 4종류:
- 성능 leak (latency, throughput, memory)
- 에러 leak (내부 에러가 외부로)
- Timing leak (cache stale, race condition)
- Resource leak (memory/handle 노출)
→ Leak을 예측 가능한 contract로 노출. Result type, metadata, timeout parameter. 감추지 말고 명시적 contract로. AI agent가 interface만 보고 작동해서 leak 인지 못함 → 이를 spec에 박는 것이 AI 시대 interface 책임.
4. 무엇이 변할 약속인가?
reversibility 명제 직접 적용:
- Type 2 (reversible) 결정 = default
- Type 1 (irreversible) 결정 = 명시적 인지
Versioning convention:
- Semver: major break / minor add / patch fix
- Deprecation policy: 언제·어떻게 deprecate
- Migration path: old → new 이동 도구
Public API published 같은 결정은 Type 1이라 신중하게*. Internal API는 Type 2로 자유롭게 진화.
✨ 좋은 Interface의 6가지 특징
매 interface 점검 시 묻는 6 질문:
| # | 특징 | 점검 질문 |
|---|---|---|
| 1 | Cohesive | 한 개념·한 책임인가? 여러 책임이 섞여 있나? |
| 2 | Complete | 사용자가 내부에 손 안 대고 자기 일을 끝낼 수 있나? |
| 3 | Convenient | 자주 쓰는 path가 짧은가? drop-and-go 가능? |
| 4 | Predictable | 같은 input → 같은 output? randomness가 명시적인가? |
| 5 | Documented | 왜 이런 design인지 + leak + edge case 적혀 있나? ADR 있나? |
| 6 | Versioned | 변할 때 명시적 약속이 있나? semver, deprecation policy? |
이 6가지가 대부분의 interface anti-pattern을 회피.
⚠️ Interface 함정
1. Leaky Abstraction (Spolsky)
Implementation detail이 새옴. interface가 거짓말이 됨.
해결: leak을 예측 가능한 contract로 노출. 감추지 않음.
2. God Interface
너무 많은 method, 너무 많은 책임. cohesion 깨짐.
해결: 책임 별로 분리. 하나의 interface가 하나의 mental model.
3. Premature Interface
도메인 모르는 채 design → 50%+ 잘못된 경계.
해결: tracer-bullets|tracer bullets로 빠르게 탐색. Rule of three (3번 같은 패턴 보이면 abstraction).
4. Interface for Testing Only (DHH 비판)
Test에 맞춘 interface가 진짜 도메인을 못 나타냄. mock 친화도가 design 결정.
해결: **Test가 interface contract를 검증하는 도구*이지 interface를 결정하는 도구가 아님. 도메인이 우선.
5. Symmetric Interface for Asymmetric Domain
Getter/setter 형식이 진짜 동작은 비대칭. 예: 읽기는 흔하고 쓰기는 드문 자원에 둘 다 같은 형태.
해결: 도메인 actual operation을 따라감. asymmetric은 asymmetric 그대로.
6. AI Agent에게 Interface Lying
Interface가 거짓말 → AI는 face value로 받음 → 잘못된 코드 양산.
해결 (information-leak-vs-abstraction 인사이트 1): Interface가 진실해야 AI가 자기 일을 함. 거짓말은 사람의 tribal knowledge로 보완 가능했지만 AI는 못 함.
🌱 Interface 진화 mechanism
처음부터 완벽한 interface 불가능. 진화 cycle:
**Interface는 살아있는 도구. 한 번 design하고 끝나는 게 아니라 증거가 쌓이며 진화. 그래서 reversibility가 핵심 — 진화 가능한 형태로 두기.
언제 Interface를 변경하는가 — 3가지 신호
매 sprint 끝에:
- 사용자가 internal 알아야 하는 경우 누적 → interface 부족 신호 → complete성 강화
- 같은 변경이 여러 곳에서 발생 → secret 격리 안 됨 → secret 새로 정의 후 interface 재구성
- AI agent가 자꾸 같은 실수 반복 → interface가 거짓말 신호 → contract 명시화
🎓 Interface 만드는 6단계 (학생 운영)
다음 프로젝트에 그대로 적용 가능한 path:
Step 1 — 사용자의 mental model 발견 (ubiquitous-language)
학생이 어떤 단어로 사고하는가?
학내 학사 도메인이라면: 수강신청·정정·폐강·정원·가산점·재수강. 이게 interface의 vocabulary.
Step 2 — 무엇이 변할지 예측 (변화 압력 분석)
매 자리에서:
- 외부 시스템 → 항상 변함 (anti-corruption-layer|ACL 격리)
- 도메인 정책 → 정기 변경 (학칙·정원 규칙)
- Vendor 결정 → 가능성 있음 (Provider trait)
- Implementation → 자주 변함 (감추기)
Step 3 — 변하는 것을 감춤 (information-hiding / deep-modules)
각 secret을 cohesive한 module 안에 격리. 작은 표면 + 풍부한 내부.
Step 4 — 사용자 경계의 최소 약속만 노출
What / When / What not / Compatibility를 명시. 최소 약속만. 더 많이 약속하면 변경 시 비용.
Step 5 — Leak을 명시적 contract로
Result type / metadata / timeout / model_config() 같은 method. 감추지 말고 예측 가능한 leak으로.
Step 6 — ADR로 왜 기록 + 언제 변경 가능한지 약속 (adr-as-strategic-mechanism|ADR)
매 큰 interface 결정마다 30분-1시간 ADR. 가정·되돌림·변화 시점까지.
→ *6단계가 strategic 시간의 사용 mechanism. 사용자가 매 sprint에 한두 번 거치는 cycle.
🌐 14 원칙으로 풀기 — Interface design의 다른 면
14 원칙이 interface design의 다른 면임을 명시:
| 원칙 | Interface design 측 표현 |
|---|---|
| deep-modules | 작은 interface, 풍부한 implementation — 가장 직접적 |
| information-hiding | interface 뒤에 무엇을 감출지 |
| information-leak-vs-abstraction | interface가 거짓말하지 않게 leak 명시화 |
| strategic-vs-tactical-programming | interface 정의 = strategic 시간의 결정체 |
| simple-not-easy | interface는 simple해야 (얽힘 없음). easy해야 하는 건 아님 |
| ubiquitous-language | interface vocabulary = 도메인 vocabulary |
| bounded-context | interface는 BC 안에서만 통일. BC 사이는 ACL |
| anti-corruption-layer | 외부 interface ↔ 내부 interface 변환 |
| orthogonality | interface 간 단방향 의존, 한 변경이 다른 interface 영향 X |
| reversibility | interface 결정도 Type 2 default. 진화 가능한 형태로 |
| tdd-as-small-deliberate-steps | test가 interface contract를 검증 |
| tracer-bullets | 최소 interface로 end-to-end 시작, 점진 확장 |
| named-ownership | interface마다 owner + success criteria 명시 |
| ship-and-rollback-as-normal | interface 변경도 ship + rollback 둘 다 normal |
→ *14 원칙은 모두 같은 interface design framework의 다른 시각. 사용자가 도달한 통찰이 14 원칙의 통합 운영 답.
🤖 AI 시대 specific — Interface가 AI에게 진실해야 함
사람 시대 vs AI 시대 차이
| 사람 시대 | AI 시대 | |
|---|---|---|
| Interface 거짓말 시 | tribal knowledge로 보완 | 그대로 잘못된 코드 양산 |
| Leak 인지 | 경험으로 자연 학습 | spec에 박혀 있어야 알게 됨 |
| 진화 흡수 | 사람이 점진 학습 | session마다 영구한 새 입사자 (Bull Memento) |
→ AI 시대에 interface는 반드시 진실해야 한다. 사람만 보던 시절보다 훨씬 더 strict.
v1.0의 4 face Interface (Multi-faced Deep Module)
synthesis-complex-to-simple#🎭 Two-faced Deep Module — 사용자 통찰의 정리|synthesis에서 정리한 4 face:
| Face | Interface | 노출 단위 |
|---|---|---|
| User-facing | "수강신청 검증해줘" 한 문장 | 자연어 명령 + 결과 |
| LLM-facing | SKILL.md frontmatter | task contract + vocabulary |
| Future-dev-facing | SKILL.md + ADR | 도구 진화 표면 |
| Operator-facing | health check / rollback | 운영 신호 |
*각 face가 해당 사용자의 mental model에 맞춘 interface. 4 face가 서로 격리되면서 통합되는 게 v1.0의 정체성.
📚 Interface 깊은 이해 — 책 추천
짧고 직접 (시작)
- Ousterhout A Philosophy of Software Design 4-9장 — 가장 직접적 source. 4장(Modules Should Be Deep) / 5장(Information Hiding) / 6장(General-Purpose Modules) / 7장(Different Layer, Different Abstraction) / 8장(Pull Complexity Downward) / 9장(Better Together Or Better Apart).
Type-driven (사용자 Rust 환경에 강추)
- Domain Modeling Made Functional — Scott Wlaschin (2018). 한국어 《도메인 주도 설계로 시작하는 함수형 프로그래밍》 (위키북스). type을 통한 interface design. F# 사용하지만 Rust/Haskell/Scala/TS에 transferable. 불가능한 상태를 type으로 표현 못 하게 만드는 명제.
- Programming Rust — Jim Blandy 등 (2nd ed, 2021). 한국어 《러스트 프로그래밍 공식 가이드》. trait가 interface의 functional 표현.
- Rust for Rustaceans — Jon Gjengset (2021). 한국어 《러스트 프로그래밍 정석》. trait + lifetime 심화.
API Design 측
- API Design Patterns — JJ Geewax (2021). 한국어 《API 디자인 패턴》. modern REST/RPC API 패턴 catalog. interface 진화·versioning까지.
- Designing Data-Intensive Applications — Martin Kleppmann (2017). 한국어 《데이터 중심 애플리케이션 설계》 (위키북스). 데이터 interface 깊이. 한국어판 평이 매우 좋음.
OOP / Pragmatic
- Object Design: Roles, Responsibilities, and Collaborations — Wirfs-Brock & McKean (2003). interface가 responsibility의 표현.
- Effective Java 3판 — Joshua Bloch (2018). 한국어 《이펙티브 자바 3판》 (인사이트). Java specific이지만 interface design tip catalog가 transferable.
추천 학습 path
1. Ousterhout 4-9장 (며칠) — interface design 직접
↓
2. Wlaschin *Domain Modeling Made Functional* (1-2주)
— type을 통한 interface, 학생 진짜 자산 형성
↓
3. (Rust 환경) Programming Rust 또는 Rust for Rustaceans
— trait 깊이
↓
4. (선택) Geewax *API Design Patterns* — 월 단위 reference
한 줄 요약
Interface는 strategic 사고가 결정체로 응결되는 자리. 사용자의 mental model에 맞춰 변하는 것을 감추고 약속을 명시. 처음부터 완벽 X — tracer bullet으로 시작, 증거 쌓이면 진화, 매 변경 ADR로 기록. 14 원칙은 모두 interface design의 다른 면이다.
이게 14 원칙 학습의 진짜 종착점이고, 그 후에는 매 sprint에 interface 정의 + 재정의가 학생의 strategic 시간의 본질.
관련
응용 자료 4총사
- synthesis-complex-to-simple — Theory (왜)
- student-application-guide — Application (언제·어디서)
- adr-as-strategic-mechanism — Mechanism (어떻게 기록)
- interface-as-strategic-surface — Surface (interface 자체) ← 이 노트
흐름: 왜 → 언제 → 어떻게 기록 → 무엇을 만드는가
14 원칙 노트 (모두 interface 측 응용)
- deep-modules — 가장 직접
- information-hiding — 무엇을 감출지
- information-leak-vs-abstraction — leak 명시화
- strategic-vs-tactical-programming — strategic 시간의 결정체
- ubiquitous-language — interface vocabulary
- bounded-context — interface 범위
- anti-corruption-layer — 외부 ↔ 내부 변환
- reversibility — 진화 가능한 형태
- tracer-bullets — 최소 interface로 시작
- tdd-as-small-deliberate-steps — interface contract 검증
외부 cross-reference
- research/stateless-llm-sdk/design-principles|design-principles — v1.0 7 원칙 (Provider trait가 interface 측 응용)
- research/stateless-llm-sdk/software-fundamentals-thesis|software-fundamentals-thesis — Matt thesis (substrate가 interface의 strategic enabler)
Sources
Interface design 직접 source
- A Philosophy of Software Design — John Ousterhout (2018, 2nd ed 2021). 4-9장
- Parnas, D.L. (1972). On the Criteria to Be Used in Decomposing Systems into Modules. 무료 PDF
Type-driven design
- Domain Modeling Made Functional — Scott Wlaschin (2018)
- Type-Driven Development with Idris — Edwin Brady (2017)
- The Rust Programming Language — Klabnik & Nichols. trait
API design
- API Design Patterns — JJ Geewax (2021)
- Designing Data-Intensive Applications — Martin Kleppmann (2017)
- Web API Design — Brian Mulloy (무료 ebook)
Strategic / Information hiding root
- No Silver Bullet — Brooks (1986). essential vs accidental complexity
- Simple Made Easy — Hickey. simple/complex/easy/hard
AI 시대 interface
- Ian Bull — Sinks, Not Pipes — architecture is the prompt (interface 측)
- Anthropic — Effective Harnesses — feature list / passes field가 machine readable interface