엔진을 먼저 세우고 클라이언트를 붙여

"전등을 고르기 전에 회로부터 만들어. 첫 전등을 먼저 사면 회로의 가능성까지 그 전등에 맞춰지거든."

만드는 순서가 책임의 방향을 정해

CWK의 엔진들은 엔진을 완성하고 API를 연 뒤 클라이언트를 붙이는 순서를 따라. 단순한 일정 선택이 아냐. 먼저 만든 구성 요소가 뒤에 오는 것의 요구에 맞춰질지, 뒤에 오는 것이 앞의 일반 계약에 적응할지를 결정하는 아키텍처야. 엔진부터 만들면 여러 클라이언트가 같은 API를 쓰지만 UI부터 만들면 API가 첫 화면의 사정을 평생 떠안아.

첫 화면의 우연이 API 언어가 될 수 있어

UI를 먼저 만들면 화면의 필터와 토글, 배치에 딱 맞는 응답을 내는 엔드포인트부터 쓰게 돼. 그 화면에는 편하지만 다음 클라이언트가 오면 필요 없는 필드를 풀고 첫 UI의 가정을 우회해야 하지. 한 화면에서만 자연스러운 표현이 엔진의 영구 계약으로 굳어버린 거야.

콘솔은 첫 제품이 아니라 첫 시험용 전구야

Lantern 콘솔은 엔진을 만든 뒤 공개 API에 처음 연결한 클라이언트야. 데이터베이스를 직접 읽거나 내부 코드를 가져오는 특별 통로를 받지 않아. 필요한 정보가 API에 없다면 공개 계약을 보완해야 한다는 신호로 삼아. 첫 클라이언트가 뒷문을 쓰면 API가 실제로 충분한지 시험할 기회를 잃어.

먼저 만든 것이 나머지의 모양을 결정해. 일반적인 능력을 먼저 만들고 특수한 화면이 거기에 적응하게 해. 자기 회사의 첫 클라이언트도 공개 경로만 사용해야 미래의 외부 클라이언트가 겪을 문제를 미리 볼 수 있어.

새 클라이언트가 엔진 변경 없이 붙으면 순서가 옳았다는 증거야

나중에 에디터 자동완성, HTTP 도구로 검색하는 비서, 사이트 검색 화면이 왔을 때 기존 엔드포인트만으로 온전한 기능을 쓸 수 있었어. 엔진 수정은 없고 각 클라이언트의 연결 작업만 필요했지. 새로운 소비자가 올 때마다 엔진을 바꿔야 한다면 범용 엔진을 만든 것이 아니라 첫 UI의 전용 백엔드를 엔진이라고 부른 셈이야.

이 순서는 UI를 중요하지 않게 본다는 뜻이 아니야. 오히려 첫 클라이언트가 공개 API의 실제 사용자가 되어 계약의 빈틈을 가장 빨리 드러내. 화면에서 필요한 기능이 없다면 내부 우회로를 만들지 말고 일반 API가 정말 가져야 할 능력인지 검토해 보완해야 해.

Code

모든 클라이언트는 공개 계약이라는 앞문을 써·python

# The engine exposes ONE public contract. Nobody gets a private door.
@app.post("/api/search")
def search(query: str, mode: str = "hybrid", k: int = 8) -> list[CitableResult]:
    ...

# Client 1 — the console. Built SECOND. A lightbulb proving current flows.
results = http.post("/api/search", json={"query": q, "mode": "hybrid"})

# Client 2 — an editor's completion popup. Arrived later. Engine changes: zero.
suggestions = http.post("/api/complete", json={"prefix": tail})

# Client 3 — an assistant calling the engine as a tool over HTTP. Also zero.
slices = http.post("/api/search", json={"query": question, "k": 8})

# The receipt for engine-first: adding clients 2 and 3 was a CLIENT-side change.
# If each new client had forced an engine change, it was never a general engine —
# it was one UI's backend wearing an engine's name.

Exercise

네가 만들거나 사용하는 API를 살펴봐. 엔드포인트만 보고도 어떤 UI를 먼저 만들었는지 알아챌 수 있는지 확인해. 특정 화면에서만 뜻이 있는 필드나 뷰 이름을 딴 필터를 찾은 다음, CLI나 봇, 다른 앱을 새 클라이언트로 붙인다고 상상해 봐. 새 클라이언트가 우회해야 할 항목을 모두 적으면, 첫 UI에 맞추느라 API가 치르는 비용이 보여.

Hint

신호는 리소스가 아니라 화면 이름을 딴 엔드포인트, 레이아웃을 그대로 따라가는 응답 모양, 특정 화면 상태를 담은 파라미터야. 이런 흔적 하나하나는 첫 클라이언트의 우연이 계약으로 굳어, 앞으로 오는 모든 클라이언트가 함께 떠안게 됐다는 뜻이야.

만드는 순서가 책임의 방향을 정해

첫 화면의 우연이 API 언어가 될 수 있어

콘솔은 첫 제품이 아니라 첫 시험용 전구야

새 클라이언트가 엔진 변경 없이 붙으면 순서가 옳았다는 증거야

Code

External links

Exercise

Progress

댓글 0