Show Cover Slide
코드 컨벤션의 역할 변화와 Design-First로 넘어가는 개발 문화
1. 코드 컨벤션, 아직도 중요한가요?
들여쓰기, 괄호 위치, 변수 이름.
여러분은 아직도 이런 부분들을 리뷰하고 계신가요?
오랜 시간 동안 우리는 코드 컨벤션을 협업의 질서를 위한 중요한 기준으로 삼아왔습니다.
스타일을 통일하고, 코드의 가독성을 높이는 것은 개발자 간 협업에서 미덕으로 여겨졌습니다.
하지만 이제는 다시 질문하게 됩니다.
정말 이것이 우리가 합의해야 할 핵심일까요?
자동 포매터는 대부분의 스타일을 자동으로 맞춰주고,
AI는 명세 없이도 코드를 생성합니다.
협업의 중심은 코드가 아니라, API 명세, 다이어그램, 문서로 이동하고 있습니다.
이러한 흐름 속에서 저는 코드 컨벤션이 점차 중심 역할을 잃어가고 있다는 사실을 실감하게 되었습니다.
그렇다면 우리는 앞으로 어떤 기준을 중심으로 협업을 이어가야 할까요?
이 글에서는 다음의 흐름을 따라갑니다.
- 코드 컨벤션이 어떤 맥락에서 등장했고, 왜 영향력을 잃어가고 있는가
- API 명세는 어떻게 협업의 기준이 되었는가
- API 명세만으로는 설명할 수 없는 설계의 맥락은 무엇인가
- 우리가 앞으로 만들고 지켜야 할 개발 문화는 어떤 모습이어야 하는가
지금은 철학을 다시 말해야 하는 시점입니다.
이제는 “코드를 어떻게 작성했는가”보다, “왜 이렇게 만들었는가”를 설명할 수 있어야 합니다.
2. Code Convention, API-First, Design-First — 개념과 등장 배경
이 글에서 다루는 세 가지 개념은 모두 협업 방식의 변화에 따라 등장한 실천 전략입니다.
각 용어는 단순한 트렌드가 아니라, 개발 환경의 복잡성 증가에 따라 필연적으로 나타난 대응이기도 합니다.
Code Convention
- 등장 배경: 협업 규모가 커지면서 코드 가독성에 대한 문제가 발생했습니다
- 역할: 스타일 통일, 리뷰 기준 제공, 유지보수 일관성 확보
- 전환 계기: 자동 포매터 도구 보편화, AI 코드 생성, 스타일 논의의 소멸
→ 현재는 도구가 자동으로 해결하는 설정값 수준의 영역으로 전환되었습니다
API-First
- 등장 배경: 클라이언트와 서버, 다수 팀 간 협업에서 계약 부재로 인한 충돌이 잦았습니다
- 역할: 명세 기반의 계약, 자동화된 협업, 병렬 개발의 기반 제공
- 확산 요인: Swagger(OpenAPI), Postman, Contract Testing 도구의 발전
- 한계: “무엇을 만들 것인가”는 정의하지만, “왜 그렇게 만들었는가”는 설명할 수 없습니다
Design-First
- 등장 배경: 도메인 복잡성 증가, API 명세만으로는 설계 판단 공유가 어려워졌습니다
- 역할: 설계 구조, 책임 분리, 의사결정의 근거를 코드 이전에 정의
- 실천 수단: ADR, 도메인 모델링, 설계 다이어그램
- 표현 확산: 2016년경 Stoplight·SwaggerHub 등에서 Design-First 용어 공식화
- 현재: 설계 중심 협업 문화로 정착되며 실천 단위(ADR, RFC 등)로 분화되고 있습니다
| 구분 | 핵심 질문 | 협업 중심 | 전환 이유 |
|---|---|---|---|
| 코드 컨벤션 | 어떻게 썼는가? | 스타일 | 자동화로 대체됨 |
| API-First | 무엇을 만들 것인가? | 인터페이스 | 병렬 개발 수요 |
| Design-First | 왜 그렇게 만들었는가? | 구조와 의도 | 복잡성 대응 필요 |
이 흐름은 협업의 단위가 코드 → 인터페이스 → 설계 판단으로 이동해온 진화를 보여줍니다.
3. 협업의 구조는 어떻게 바뀌고 있는가
과거의 협업은 코드 그 자체를 중심으로 이루어졌습니다.
어떤 스타일로 작성했는지, 어떻게 정렬하고 네이밍했는지를 맞추는 것이 팀워크의 상징이자 필수 조건처럼 여겨졌습니다.
그러나 오늘날, 협업의 구조는 점차 그 중심을 잃고 있습니다.
- 자동 포매터가 대부분의 스타일 논의를 제거했습니다
- AI는 컨벤션과 무관하게 코드를 생성하며, 리뷰 기준이 흔들리고 있습니다
- 많은 스타트업은 빠른 실험과 폐기를 반복하며 스타일보다 실행 가능성과 속도를 우선시하고 있습니다
이러한 변화는 협업의 기준을 코드 스타일에서 인터페이스 명세, 그리고 그보다 더 근본적인 설계 구조와 판단으로 옮기고 있습니다.
- 어떤 기능을 만들 것인가(API 명세)
- 누가 어떤 책임을 질 것인가(도메인 모델)
- 왜 그렇게 설계했는가(의사결정 기록)
이제 협업은
“어떻게 썼는가”보다
“왜 그렇게 만들었는가”를 함께 이해하고 공유하는 구조로 진화하고 있습니다.
코드 중심 협업은 저물고 있으며,
지금은 판단과 설계의 흐름을 공유하는 구조가 필요합니다.
4. API-First: 소통의 기술적 표준화
협업이 커지고, 시스템이 복잡해질수록
개발자들은 더 이상 “코드를 먼저 작성하고 맞춰가는 방식”으로는 효율적인 협업을 유지하기 어려워졌습니다.
이러한 문제를 해결하기 위해 등장한 접근이 API-First입니다.
이는 기능 구현 이전에 인터페이스 명세를 먼저 정의하고, 이를 기준으로 개발을 병렬로 진행하는 방식입니다.
API-First가 만들어낸 변화
인터페이스가 계약이 됩니다
OpenAPI, GraphQL, gRPC 등 명세 포맷을 통해 일관된 협업 기준을 제공합니다
개발이 병렬화됩니다
클라이언트와 서버가 명세를 기준으로 독립적으로 작업할 수 있습니다
Mock 서버, 자동화된 문서, 테스트 스텁 생성 등 다양한 도구가 이를 지원합니다
소통이 명세를 중심으로 바뀝니다
과거처럼 구현된 코드를 기준으로 논의하지 않고, 명세와 설계 기준을 중심으로 의사결정을 내립니다
이 방식은 명확한 효율성과 생산성 향상을 가져왔습니다.
그러나 한 가지 중요한 한계도 존재합니다.
API 명세는 “무엇을 만들 것인가”는 설명할 수 있지만,
“왜 그렇게 만들었는가”는 설명하지 못합니다.
- 도메인 경계가 왜 그렇게 나뉘었는지
- 특정 기능을 왜 이 서비스가 담당하는지
- API 변경이 어떤 맥락에서 결정되었는지
이러한 판단의 근거는 대부분 명세 밖에 존재하며,
공유되지 않거나, 잊히거나, 문서화되지 않은 채 사라집니다.
그래서 우리는 명세 중심 협업을 넘어,
설계의 흐름과 판단을 함께 공유하는 구조가 필요하다고 느끼게 됩니다.
5. 설계 중심 개발: 복잡성에 대응하는 전략적 흐름
도메인이 복잡해질수록, 협업에서 필요한 것은
단순한 코드 공유나 인터페이스 명세 이상의 것이 됩니다.
기능이 늘어나고,
팀이 분화되며,
서비스가 분리될수록
개발자들은 코드가 아니라 구조,
그리고 판단의 흐름을 공유해야 할 필요성을 느끼게 됩니다.
이러한 배경에서 실천되고 있는 방식이
바로 설계 중심 개발입니다.
일반적으로는 ‘Design-First’라고 불리기도 하지만, 최근에는 더 구체적인 실천 방식으로 나뉘어 사용되고 있습니다.
설계 중심 개발에서 다루는 핵심 요소
도메인 모델링
시스템의 기능과 책임을 구획하고, 구조적으로 나누는 기준을 세웁니다
설계 흐름의 시각화
시퀀스 다이어그램, 상태 전이, 컴포넌트 구성 등 협업을 위한 구조적 이해를 문서화합니다
ADR (Architecture Decision Record)
특정 구조나 기술을 선택한 이유, 고려했던 대안, 배경을 명확히 기록합니다
RFC 기반 설계 협업
팀 간 설계 제안과 피드백을 문서화하고, 검토 가능한 형식으로 관리합니다
설계 중심 개발은 API를 먼저 정의하는 것 이상의 의미를 갖습니다.
이는 구조를 판단 가능한 방식으로 설명하고, 그 판단을 팀 전체가 이해하고 공유하는 협업의 방식입니다.
코드를 통해 구현되는 것은 이미 결정된 구조의 결과물일 뿐입니다.
중요한 것은 “무엇을 만들 것인가”보다
“왜 그렇게 만들었는가”를 설명할 수 있는 구조입니다.
6. 앞으로의 문화는 어떻게 달라져야 하는가?
개발 환경이 복잡해지고 협업의 주체가 다양해질수록, 우리에게 필요한 것은 코드 스타일을 맞추는 문화가 아니라
판단 가능한 구조와 의사결정의 흐름을 공유하는 문화입니다.
협업의 방식은 달라졌습니다.
이제는 그에 걸맞은 개발 문화로의 전환이 필요합니다.
우리가 만들어가야 할 협업 방식
코드 스타일은 도구에 맡깁니다
Prettier, Black, gofmt 등 자동화된 포매터를 통해 스타일 논쟁을 제거합니다
인터페이스는 명세로 계약합니다
OpenAPI, GraphQL, Protobuf 등을 활용해 명확한 계약 기준을 기반으로 협업을 진행합니다
설계 판단은 기록으로 남깁니다
ADR, RFC 등을 통해 설계 결정의 배경과 맥락을 공유합니다
ADR, RFC가 반드시 필요하다는 주장이 아닙니다. 설계판단이 지식화 되는 방법을 찾을 필요성을 의미합니다.
책임과 구조는 설계 단계에서 합의합니다
도메인 모델링과 컴포넌트 구획을 통해 팀 간 책임 분리와 협업 구조를 명확히 합니다
우리는 더 이상
- 변수명을 논의하고
- 포맷팅을 리뷰하며
- 기능의 의도를 추정하는 협업 방식으로 일할 수 없습니다.
앞으로는
“무엇을 만들었는가”보다
“왜 그렇게 만들었는가”를 설명할 수 있는 시스템이 필요합니다.
설계는 이제 협업의 출발점이며,
그 설계를 공유하는 문화는 팀의 확장성과 유지보수성에 직결됩니다.
7. 우리는 무엇을 합의해야 하는가?
코드 컨벤션은 오랜 시간 동안 협업의 질서를 만들어 주는 중요한 도구였습니다.
그리고 지금도 여전히 유효한 규범으로 작동하고 있습니다.
하지만 저는 점점 더 많은 팀들이
이제는 코드 스타일보다
설계의 구조와 판단의 흐름을 중심으로 협업하고 있다는 사실을 느끼고 있습니다.
자동화된 포매터,
AI 기반의 코드 생성,
그리고 API 명세 중심의 개발 방식은
협업의 기준을 코드에서 명세로,
그리고 명세에서 설계로 이동시키고 있습니다.
우리가 앞으로 합의해야 할 것은 단순히 코드를 일관되게 작성하는 것이 아닙니다.
- 무엇을 만들 것인지에 대한 명확한 인터페이스
- 왜 그렇게 만들었는지에 대한 구조적 판단
- 그리고 그 판단이 어떻게 기록되고 공유되어야 하는지에 대한 문화
구조의 중요성을 말해왔습니다.
Design-First가 필요하다고 말해왔습니다.
아직은 익숙하지 않은 생각의 시간이라고 생각합니다.
그래서 이 글을 다시 씁니다.
지금은 계속해서 전파하고 설득해 나가야 할 시간이라고 생각하기 때문입니다.
코드 컨벤션은 도구가 대신하게 되었습니다.
우리가 진정으로 합의해야 할 것은
코드가 아니라 구조이며, 구현이 아니라 판단 가능한 설계의 흐름입니다.
첨부 : Code Convention, API-First, Design-First의 연혁 정리
Code Convention
| 연도 | 사건/흐름 |
|---|---|
| 1968 | Edsger Dijkstra, 구조적 프로그래밍 주장 (“Go To Statement Considered Harmful”) |
| 1974 | Kernighan & Plauger, 『The Elements of Programming Style』 출간 |
| 1978 | K&R C 스타일 등장, 이후 각 언어별 컨벤션 형성 |
| 1990s | Java, C++, Python 등 언어 중심 스타일 가이드 확산 |
| 2010s | ESLint, PEP8, gofmt 등 린터/포매터의 자동화 도입 |
| 2020s~ | Prettier, Black, clang-format 등 도구 중심 자동 포맷 정착 |
컨벤션은 점차 사람이 아닌 도구가 지키는 영역으로 이동
API-First
| 연도 | 사건/흐름 |
|---|---|
| 2000s 초 | SOAP/XML 기반 웹 API 등장 (Salesforce, eBay, Amazon 등) |
| 2011 | Swagger (후에 OpenAPI) 공개: 명세 기반 API 개발 시작 |
| 2014~2017 | Google Cloud API Design Guide, Microsoft REST Guidelines 등 대기업 기준 공개 |
| 2016 | Swagger → OpenAPI로 재정립, Linux Foundation 주관 |
| 2018~ | Stoplight, Postman, Pact 등 API 설계/문서화 도구 확산 |
API 명세가 협업의 계약이 되고, 개발 병렬화의 기반이 됨
Design-First
| 연도 | 사건/흐름 |
|---|---|
| 2010년대 초반 | Domain-Driven Design(DDD)와 함께 시스템 구조 설계 중심 문화 논의 |
| 2015 | ADR(Architecture Decision Record) 문화 확산 (Michael Nygard 외) |
| 2016~2017 | Stoplight, SwaggerHub 등 API 설계 도구에서 “Design-First”라는 용어 사용 시작 |
| 명세 중심(API-First) 개발을 넘는 개념으로 ‘설계 우선 접근’을 명시화 | |
| 2016~2020 | API-First에 포함된 흐름으로 “의도와 설계의 기록” 요구 부상 |
| 2020s | RFC 기반 협업, 도메인 모델링, 설계 시각화 등 실천형 도구와 함께 정착 |
“API 명세 이전의 구조적 합의”를 문화로 정착시키는 흐름
이 세 가지 개념은 모두 개발 환경의 복잡성 증가와
협업의 단위 변화에 대응하기 위해 발전해왔습니다.
첨부 : RFC (Request for Comments)란 무엇인가요?
RFC(Request for Comments)는 팀 또는 조직 내에서 새로운 설계, 정책, 구조 변경을 제안하고 그에 대한 피드백을 받기 위해 작성하는 문서입니다.
목적
- 특정 기능이나 구조 변경을 공식적으로 제안하고
- 다양한 구성원으로부터 피드백을 수렴하여
- 변경 사항을 조율된 설계안으로 발전시키기 위한 과정입니다.
이는 단순한 아이디어 메모가 아니라, 조직의 합의 기반 설계를 위한 문서 기반 커뮤니케이션 방식입니다.
주요 활용 방식
- 기능 또는 아키텍처 변경을 사전에 공유하고
- 피드백과 토론을 문서 기반으로 이끌어내며
- 리뷰 및 승인 과정을 명확히 합니다
- 최종 설계안은 기록으로 남아, 향후 참조 가능합니다
형식 예시
- 제목 및 번호
- 제안자와 작성일
- 변경 제안의 배경
- 구체적인 설계 또는 정책 내용
- 예상되는 영향 및 대안
- 피드백 로그 및 결정 사항
RFC는 단순한 문서가 아니라,
팀의 판단과 설계를 명시적으로 조율해 나가는 과정을 담는 도구입니다.
첨부 : ADR (Architecture Decision Record)란 무엇인가요?
ADR(Architecture Decision Record)는 소프트웨어 시스템을 설계하거나 구성할 때 내렸던 특정 결정의 배경과 이유, 대안을 명확하게 기록하는 문서입니다.
목적
- 어떤 구조나 기술을 왜 선택했는지
- 그 결정은 어떤 문제에 대한 해법이었는지
- 어떤 대안들이 고려되었고 왜 채택되지 않았는지를 명시합니다.
이를 통해, 시간이 지나도 설계의 의도를 이해할 수 있도록 도와줍니다.
주요 활용 방식
- 프로젝트 초기뿐 아니라 개발 도중에도 계속 작성됩니다
- 결정은 버전별로 누적되어 기록되며, 변경 이력도 함께 관리됩니다
- ADR을 통해 설계의 일관성을 유지하고, 의사결정의 근거를 남길 수 있습니다
형식 예시
- 결정 제목 및 식별자
- 상태 (예: 제안됨, 승인됨, 폐기됨 등)
- 맥락 (Context): 어떤 문제가 있었는가
- 결정 (Decision): 어떤 선택을 했는가
- 근거 (Rationale): 왜 그렇게 했는가
- 대안 (Alternatives): 무엇을 고려했으며 왜 선택하지 않았는가
- 후속 조치 또는 관련 문서
ADR은 팀이 설계를 통해 “왜 이렇게 만들었는가”를 설명할 수 있도록 돕는 기록 장치입니다.
기술적인 결정이 개인의 기억이 아닌, 조직의 자산으로 남을 수 있도록 해줍니다.
홈으로 가기