2nd/10_Wiki/Topics/Architecture/Conceptual Integrity.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-conceptual-integrity	Conceptual Integrity	10_Wiki/Topics	verified	self	Architectural Integrity Brooks Conceptual Integrity	none	A	0.9	applied	architecture design brooks mythical-man-month		2026-05-10	pending	language framework agnostic agnostic

Conceptual Integrity

매 한 줄

"매 system design 의 the most important consideration — 매 unified set of design ideas, 매 single mind 의 product.". Brooks 의 Mythical Man-Month (1975) 의 central thesis. 매 great system 은 매 small group of architects 의 vision. 2026년 design systems, API design, programming language design, framework architecture 에 핵심 원칙으로 산다.

매 핵심

매 Brooks 의 정의

"Conceptual integrity is the most important consideration in system design. It is better to have a system omit certain anomalous features and improvements, but to reflect one set of design ideas, than to have one that contains many good but independent and uncoordinated ideas."

매 implications

• Architect/designer 의 separation from implementation team.
• Say no to features that violate the model.
• Programmer's manual = single source of truth.
• Small architect group > committee — 매 "design by committee" 의 X.

매 modern manifestations

• API design: consistent verbs, naming, error model (Stripe, GitHub APIs).
• Programming languages: Go's "less is more", Rust's ownership model.
• Frameworks: Rails "convention over configuration", Django "batteries included with one way".
• Design systems: single token vocabulary, predictable behaviors.

매 Tension

• Conceptual integrity vs feature completeness.
• Single architect vs distributed teams.
• Stability vs evolution.

매 응용

1. API design (REST resource model 의 일관성).
2. Language design (Go, Elm).
3. UI framework (SwiftUI, Jetpack Compose).
4. CLI design (git, kubectl).

💻 패턴

Consistent API model (Stripe-style)

// Every resource follows: list, retrieve, create, update, delete
GET    /v1/customers           // list
GET    /v1/customers/:id       // retrieve
POST   /v1/customers           // create
POST   /v1/customers/:id       // update (Stripe uses POST not PUT)
DELETE /v1/customers/:id       // delete

// Same shape for charges, subscriptions, invoices, ...

Consistent error model

// Every error response follows the same shape
type ApiError = {
  error: {
    type: 'invalid_request' | 'authentication' | 'rate_limit' | 'server';
    code: string;
    message: string;
    param?: string;
    request_id: string;
  };
};

Convention over configuration (Rails-like)

# Filename, class name, table name, route — all derived by convention
# app/models/article.rb       → Article class → articles table
# app/controllers/articles_controller.rb → /articles routes
class Article < ApplicationRecord
  # No XML config needed
end

Single mental model — Go's error handling

// One pattern for errors, used everywhere
result, err := doThing()
if err != nil {
    return nil, fmt.Errorf("doThing failed: %w", err)
}
// No exceptions, no Result<T,E>, just (T, error)

Architecture Decision Records (ADRs) preserve integrity

# ADR-007: All write APIs return the full resource

## Status
Accepted

## Context
Mixing return shapes (id-only vs full object) violates conceptual integrity.

## Decision
All POST/PUT/PATCH endpoints return the full updated resource.

## Consequences
- Slightly larger response bodies.
- Clients never need a follow-up GET after write.

"Say no" guard — RFC review

## Proposal
Add a special-case `/users/me/notifications/digest` that returns
HTML instead of JSON.

## Reviewer
Rejected. All API endpoints return JSON. Render HTML in client
or build a separate `/email-templates/*` namespace.

매 결정 기준

상황	Approach
Public API design	Strict consistency, single architect, "no" gate
Internal tooling	Conventions documented, ADRs
Framework	One canonical way per task
Multi-team product	Style guide + design system + design council
Research/exploration	Looser — ideas before integrity

기본값: Small architect council (2-4 people), written design principles, ADRs, explicit "rejected" log.

🔗 Graph

• 부모: Software Architecture
• 변형: Design Principles
• 응용: API Design · Design Systems · ADR

🤖 LLM 활용

언제: API design review, framework architecture, design system kickoff, language design, contested feature decisions. 언제 X: 1-week prototype, research spike, throwaway script.

❌ 안티패턴

• Design by committee: 모두가 한 마디씩 — 매 disjoint feature soup.
• Feature creep without rejection: 매 yes — 매 integrity 의 erosion.
• Multiple ways to do same thing: Python's "one obvious way" violation — choice paralysis.
• No written principles: implicit consensus — 매 architect 떠나면 깨짐.

🧪 검증 / 중복

• Verified (Brooks "Mythical Man-Month" 1975/1995 anniversary ed. / Stripe API design / Go FAQ).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — Brooks definition + modern API/framework 적용