awesome-architecture - 코드 대신 아키텍처를 가르치는 오픈소스 지식 베이스

GitHub에 study8677/awesome-architecture라는 저장소가 있습니다. 이름은 흔한 awesome 리스트처럼 보이지만, 안을 열어보면 링크 모음이 아닙니다. "코드가 아니라 아키텍처"를 가르치겠다는, 꽤 분명한 주장을 가진 지식 베이스입니다.

한 줄로 요약하면 이렇습니다. 아키텍트처럼 생각하는 법을 단계별로 가르치는 튜토리얼 9장과, 실제로 유명한 시스템들을 "어떻게 만드는가"가 아니라 "어떻게 설계되어 있는가" 관점으로 분해한 템플릿 25개로 이루어져 있습니다. 라이선스는 MIT, 중국어와 영어 이중 언어로 작성되어 있고, 온라인 인터랙티브 버전도 있습니다. 이 글에서는 이 저장소가 무엇을 담고 있는지, 그리고 그 주장이 설득력 있는지 자세히 들여다보겠습니다.

왜 지금 "아키텍처 사고"를 말하는가

이 저장소의 출발점은 다소 도발적입니다. "코딩이라는 행위가 사라지고 있다"는 진단이죠. 더 정확히는, 사람이 직접 하는 희소한 손기술로서의 코딩이 끝나가고 있다는 이야기입니다.

저자의 논리는 이렇습니다. OpenAI나 Anthropic 같은 최전선 연구소에서는 이미 코드 대부분을 LLM이 작성합니다. 사람 엔지니어는 두 가지만 합니다. 무엇을 만들지 LLM에게 말해주고, 만들어진 결과가 맞는지 판단하는 것이죠. 기계가 몇 초 만에 돌아가는 코드를 뱉어내는 순간, "for를 쓸까 map을 쓸까", "이 API를 외웠나", "이 문법에 익숙한가" 같은 옛날 무기들은 하룻밤 사이에 값어치를 잃습니다.

저자가 말하는, 값이 떨어지지 않고 오히려 비싸지는 능력은 따로 있습니다. 첫 줄을 쓰기 전에 이 시스템이 어떤 모양이어야 하는지 먼저 그려보는 판단력입니다. 데이터는 어디서 와서 어디로 가는가, 어느 부분은 강한 일관성이 필요하고 어느 부분은 최종 일관성으로 충분한가. 이게 바로 아키텍처 사고이고, 특정 언어나 프레임워크, 올해 유행하는 무언가와 무관한 능력이라는 겁니다.

저는 이 진단에 절반쯤 동의합니다. "코딩이 완전히 사라진다"는 표현은 과장에 가깝고, 실제로는 손으로 짜던 일이 검토하고 지시하는 일로 옮겨가는 쪽에 가깝죠. 다만 "지도를 먼저 보고 길을 나선다"는 비유 자체는 시대와 상관없이 옳습니다. AI가 구현을 대신해줄수록, 무엇을 시킬지 정확히 아는 사람의 값이 올라가는 건 자연스러운 흐름입니다.

저장소는 두 갈래로 나뉩니다

구조는 단순합니다. 폴더가 둘뿐입니다.

awesome-architecture/
├── tutorial/      교재 - 아키텍트처럼 생각하는 법을 체계적으로
└── templates/     템플릿 - 실제 유명 시스템의 아키텍처 지도

tutorial/는 "프레임워크 사용법"이 아니라 "옮겨 쓸 수 있는 사고법"을 가르칩니다. 모호한 요구사항을 제약으로 쪼개는 법, 취사선택 속에서 결정하는 법, 소통 가능한 아키텍처 다이어그램을 그리는 법, 0에서 새 시스템을 설계하는 법 같은 것들이죠. 9개 장으로 구성되어 있습니다.

templates/는 결이 다릅니다. 각 템플릿이 하나의 "아키텍처 지도"입니다. 의도적으로 어떤 언어, 어떤 프레임워크를 쓸지는 다루지 않습니다. 대신 이 부류의 시스템이 무슨 문제를 푸는지, 어떤 부품으로 이루어지는지, 데이터가 어떻게 흐르는지, 규모가 커지면 어디서 죽는지에 집중하죠. 각 템플릿 끝에는 실제 오픈소스 프로젝트나 엔지니어링 문서 링크가 붙어서, 소스를 따라가며 더 깊이 팔 수 있게 되어 있습니다.

아키텍트의 사고 프레임워크

튜토리얼에서 가장 실전적인 부분은 2장입니다. 모호한 요구사항을 방어 가능한 설계 결정으로 바꾸는 6단계 흐름을 제시합니다.

요구사항 → 제약 → 품질 속성 → 후보 해법 → 취사선택 → 결정

여기서 중요한 건 이게 직선이 아니라는 점입니다. 비즈니스나 규모가 바뀌면 다시 처음으로 돌아가 한 바퀴를 돕니다.

첫 단계에서 저자가 강조하는 건 두 종류의 요구사항을 구분하라는 것입니다. 기능 요구사항(시스템이 무엇을 하는가, 예를 들어 "이미지 업로드")과 품질 속성(얼마나 잘 하는가, 예를 들어 성능 목표나 확장성 목표)이죠. 핵심 통찰은 이렇습니다. 기능은 시스템이 쓸 만한지를 결정할 뿐이고, 어떻게 만들지를 결정하는 건 품질 속성이라는 겁니다. 100명을 위한 사진 공유 서비스와 수십억 명을 위한 사진 공유 서비스는 근본적으로 다른 물건이니까요.

두 번째 단계인 제약은 협상 불가능한 경계선입니다. 팀 규모와 역량, 일정 압박, 예산 상한, 규제 요건, 기존 시스템 의존성 같은 것들이죠. 여기서 나오는 통찰이 좋습니다. 제약은 결정을 복잡하게 만드는 게 아니라 선택지를 지워줘서 결정을 쉽게 만든다는 겁니다.

세 번째 품질 속성은 10가지 체크리스트로 정리됩니다. 성능, 가용성, 신뢰성과 내구성, 확장성, 일관성, 보안, 비용, 유지보수성, 관측 가능성, 진화 가능성. 시스템마다 이 각각의 중요도와 목표 수준을 따져보는 거죠.

그리고 이 프레임워크를 관통하는 원칙이 하나 있습니다.

은탄환은 없고, 오직 취사선택만 있다.

모든 아키텍처 선택은 무언가를 희생합니다. 속도를 원하면 비용이 더 들거나 일관성을 양보해야 하고, 강한 일관성을 원하면 성능과 가용성을 내줘야 하며, 확장성을 키우면 복잡성이 올라갑니다. 저자는 "취사선택이 보이는 것"이 곧 명료하게 생각하고 있다는 증거라고 말합니다. 취사선택이 안 보이면 그건 못 본 게 아니라 아직 이해하지 못한 거라는 거죠.

특히 마음에 들었던 건 요구사항을 캐낼 때 던지는 여섯 가지 질문입니다. 저자는 이를 "영혼을 묻는 여섯 질문"이라고 부릅니다.

1. 현재 규모와 피크 규모는?
2. 읽기와 쓰기 비율은?
3. 일관성 요구 수준은?
4. 성장 전망은?
5. 장애가 났을 때 결과는?
6. 팀, 시간, 예산, 컴플라이언스 제약은?

저자는 단축 URL 서비스를 예로 들어 이 여섯 질문이 어떻게 품질 목표(읽기 성능, 확장성, 내구성, 최종 일관성, 비용 효율)로 이어지고, 그 목표가 다시 캐싱 전략, 키-값 저장소, ID 생성 방식 같은 구체적 결정으로 내려가는지 보여줍니다. 추상적인 원칙으로 끝내지 않고 실제 설계로 떨어뜨리는 부분이 이 튜토리얼의 강점입니다.

10대 핵심 패턴

4장은 열 가지 아키텍처 패턴을 각각 "무슨 문제를 푸는가", "어떤 구조인가", "무엇을 희생하는가", "언제 쓰는가"로 정리합니다. 표로 옮기면 이렇습니다.

이 장이 끝나면서 저자가 못을 박는 문장이 인상적입니다.

패턴은 도구이지 목표가 아니다. "고급" 패턴도 "원시적" 패턴도 없고, 오직 "적합한" 패턴과 "부적합한" 패턴만 있다. 제대로 쓴 모놀리스는 잘못 쓴 마이크로서비스를 압도한다.

마이크로서비스를 기본값처럼 깔고 시작하는 분위기에 대한 정직한 반례죠. 저자는 마이크로서비스가 세 조건이 동시에 맞을 때만 의미 있다고 못 박습니다. 팀이 충분히 크고, 독립 배포가 분명히 필요하고, 그걸 받쳐줄 플랫폼 역량이 이미 있을 때입니다.

25개 실전 시스템 템플릿

여기가 이 저장소의 진짜 알맹이입니다. 현재 25개 템플릿이 세 묶음으로 나뉩니다.

첫째, 경전 같은 일반 시스템 16개입니다.

이 표만 봐도 시스템 설계 면접 단골 주제가 거의 다 들어있습니다. 초과판매 방지, 피드 확산, 메시지 순서, 스트리밍 출력 같은 것들이죠. 예를 들어 결제 시스템의 "멱등성, 복식부기, 대사, 상태 기계"는 그냥 키워드 나열이 아닙니다. 같은 결제 요청이 두 번 들어와도 한 번만 처리되게 하는 멱등성, 돈의 이동을 차변과 대변으로 동시에 기록하는 복식부기, 우리 기록과 외부 기록을 맞춰보는 대사, 그리고 결제의 생애주기를 명시적 상태로 관리하는 상태 기계. 이 네 가지가 왜 결제 시스템의 뼈대인지를 설명하는 구조입니다.

둘째, LLM 시대에 새로 생긴 AI 네이티브 시스템 5개입니다.

셋째, 2026년에 새로 들어간 AI 코딩 / 자율 에이전트 4개입니다. 실제로 쓰이는 에이전트 제품의 아키텍처를 다룹니다.

세 번째 묶음이 흥미로운 건, 보통 awesome 리스트가 잘 안 다루는 "에이전트 제품 자체의 아키텍처"를 정면으로 분해한다는 점입니다. 마침 제가 지금 쓰고 있는 도구이기도 해서, Claude Code 템플릿은 따로 자세히 보겠습니다.

Claude Code를 아키텍처로 분해하면

Claude Code 템플릿은 이 시리즈에서 가장 정성스러운 편입니다. 단순히 "코드 자동완성 도구"가 아니라, 스스로 맥락을 모으고 행동하고 검증하는 자율 에이전트로 Claude Code를 규정하고, 그 설계 결정을 하나씩 뜯어봅니다.

출발점이 되는 통찰은 이겁니다. "답은 모델 머릿속이 아니라 당신의 코드베이스, 당신의 에러 메시지, 당신의 실행 결과 안에 있다." 그래서 핵심 구조가 3막짜리 루프입니다.

1. 맥락 수집 - 파일 읽기, 패턴 검색, CLAUDE.md와 메모리 로드, 규칙/스킬 가져오기
2. 행동      - 파일 편집, 명령 실행, 웹 검색, 서브에이전트 파견
3. 결과 검증 - 출력 확인, 에러 점검, 완료되거나 예산이 소진될 때까지 반복

여기까지는 다른 AI 에이전트 플랫폼과 비슷합니다. 그런데 Claude Code가 갈라지는 지점은 두 가지입니다. 로컬 우선이라는 점, 그리고 파괴적인 능력(파일 삭제, 명령 실행)을 가졌다는 점이죠. 그래서 우아한 오케스트레이션보다 안전에 집착해야 한다는 게 이 템플릿의 핵심 주장입니다.

가장 중요한 설계 결정은 이중 권한 모델과 OS 수준 샌드박스를 겹쳐 쌓는 것입니다. 그 근거가 명료합니다.

모델의 지시가 영향을 미칠 수 있는 모든 계층은, 단단한 경계가 될 수 없다.

무슨 뜻이냐면, 모델이 읽는 모든 외부 콘텐츠(웹페이지, 도구 출력)에는 프롬프트 인젝션이 숨어 있을 수 있다는 겁니다. 그러니 "CLAUDE.md에 보안 규칙을 써두자" 같은 발상은 위험합니다. 인젝션 한 방에 뚫리니까요. 그래서 Claude Code는 모델이 손댈 수 없는 곳에 안전 경계를 둡니다. 세 겹입니다.

첫째, 권한 규칙입니다. deny → ask → allow 순으로 평가하고, 최우선인 deny는 모델이 절대 뒤집을 수 없습니다. 둘째, 권한 모드입니다. plan 모드는 읽기 전용, acceptEdits는 자동 승인 같은 전역 토글이죠. 셋째, OS 샌드박스입니다. macOS의 Seatbelt, 리눅스의 bubblewrap으로 Bash 하위 프로세스를 격리하고 네트워크와 파일시스템을 제한합니다. 프롬프트 인젝션이 deny 규칙을 못 넘고, 모델이 커널 수준 격리를 못 빠져나갑니다.

두 번째로 비중 있게 다루는 건 컨텍스트 윈도우 관리입니다. 토큰이 유한하니, 점진적으로 아끼는 전략을 씁니다.

• 자동 압축: 초반 대화를 요약하면서 CLAUDE.md를 디스크에서 다시 읽어들여 핵심 규칙이 사라지지 않게 합니다.
• 서브에이전트 격리: 하위 작업의 지저분한 출력이 본 대화를 오염시키지 않도록 독립된 컨텍스트 윈도우를 줍니다.
• 지연 로딩: 스킬은 시작 시 설명만 읽고 전체 내용은 필요할 때, MCP 도구 스키마도 필요할 때 가져옵니다.
• 영속 메모리: 세션을 넘는 학습을 로컬에 저장하되, 감사 가능하고 수정 가능하게 둡니다.

이 마지막 부분이 재미있습니다. 제가 지금 쓰고 있는 메모리 시스템이 바로 그겁니다. 그리고 템플릿은 분명하게 못 박습니다. 메모리는 "힌트"이지 코드 상태의 진실 원천이 아니라고요. 진실 원천은 버전 관리 시스템이고, 메모리는 만료되거나 충돌할 수 있으니 정기적으로 검토하고 고쳐야 한다는 겁니다. 이 저장소의 CLAUDE.md에도 "스냅샷, 캐시, 기억 기반 덮어쓰기 절대 금지"라는 규칙이 있는데, 정확히 같은 철학이죠.

설계 결정마다 "무엇을 버리고 무엇을 얻었는가"를 명시하는 형식도 좋습니다. 예를 들어 도구 스키마 지연 로딩은 이렇게 정리됩니다. 거부한 선택은 모든 MCP 스키마를 미리 로드하는 것(서버 20개면 막대한 컨텍스트 낭비). 택한 선택은 시작 시 설명만, 내용은 도구 검색으로 필요할 때. 비용은 도구 검색 인프라가 필요하다는 것, 얻는 것은 컨텍스트 절약. 모든 결정을 이렇게 취사선택의 언어로 적어둔 게, 앞서 튜토리얼이 가르친 "취사선택이 보여야 이해한 것"이라는 원칙과 일관됩니다.

템플릿은 안티패턴도 솔직하게 나열합니다. "CLAUDE.md에 보안 규칙을 쓰겠다"(인젝션에 뚫림), "완전성을 위해 CLAUDE.md를 최대한 키우겠다"(컨텍스트 예산을 잡아먹음), "안전을 위해 모든 곳에 ask 규칙을 걸겠다"(질문 피로 때문에 결국 눈 감고 승인하게 됨) 같은 것들이죠. 마지막 항목은 보안과 사용성의 긴장을 정확히 짚은 지적입니다.

참고로 이 저장소에는 architecture-copilot라는 짝꿍 도구도 있습니다. 이 지식을 Claude Code나 Cursor, Codex 안에서 한 단계씩 아키텍처 설계를 안내하는 인터랙티브 스킬로 바꿔주는 것이라고 합니다. 지식 베이스를 읽는 데서 끝내지 않고 실제 설계 과정에 끼워 넣겠다는 의도가 보입니다.

직접 써보려면, 그리고 아쉬운 점

저자는 독자 유형별로 사용법을 제안합니다. 초보자나 아키텍처 사고로 전환하려는 사람은 tutorial/를 순서대로 읽고, 한 장이 끝날 때마다 templates/에서 관심 있는 시스템을 골라 방금 배운 틀로 "읽어내는" 연습을 하라고 합니다. 새 시스템을 설계 중이라면 7장에서 방법론을 익히고 가장 비슷한 템플릿을 정답이 아니라 출발점으로 삼아 "핵심 결정"과 "흔한 함정"을 항목별로 자문해보라고 하죠. 시스템 설계 면접 준비라면 템플릿이 통일된 형식으로 고빈도 주제를 덮고 있어 체계적 복습에 맞고, 시니어라면 각 템플릿의 "핵심 결정과 취사선택", "진화 경로"만 봐도 된다고 합니다.

읽는 세 가지 원칙도 좋습니다. 첫째, "왜"를 먼저 묻고 "어떻게"는 나중에. 모든 아키텍처 선택 뒤에는 어떤 제약이나 취사선택이 있고, 그게 안 보이면 이해 못 한 것이다. 둘째, 최고의 아키텍처는 없고 가장 적합한 아키텍처만 있다. 같은 "채팅"이라도 내부 도구와 위챗은 정답이 천지 차이다. 셋째, 아키텍처는 자란다. 성숙기의 아키텍처를 MVP에 들이대지 말 것.

그럼 아쉬운 점은 없을까요. 몇 가지 짚어보겠습니다.

첫째, 깊이의 편차가 큽니다. Claude Code 같은 최신 템플릿은 결정 근거와 데이터 흐름까지 촘촘한데, 경전 시스템 16개 중 일부는 면접 대비 요약에 가깝게 얕을 수 있습니다. 같은 형식을 쓴다고 같은 깊이가 보장되지는 않죠.

둘째, "코딩이 사라진다"는 프레이밍은 마케팅에 가깝습니다. 실제로는 손코딩이 검토와 지시로 무게중심이 옮겨가는 것이고, 그 과정에서도 코드를 읽고 디버깅하는 능력은 여전히 필요합니다. 아키텍처 사고가 중요하다는 결론은 맞지만, 그걸 강조하려고 코딩을 과하게 깎아내린 인상이 있습니다.

셋째, 항목들이 빠르게 낡습니다. AI 네이티브와 자율 에이전트 묶음은 2026년 현재의 스냅샷이고, vLLM이나 Dify, Codex 같은 도구의 아키텍처는 분기 단위로 바뀝니다. 끝에 실제 프로젝트 링크를 달아둔 건 그래서 현명한 보완책입니다. 원문을 따라가 최신 상태를 직접 확인하라는 거니까요.

종합하면, 이 저장소는 "링크 모음" 부류의 awesome 리스트가 아니라 분명한 관점을 가진 교재 겸 사례집입니다. 특히 시스템 설계를 통일된 틀(문제, 부품, 데이터 흐름, 핵심 결정, 함정, 진화 경로)로 반복해서 보여준다는 점에서, 면접 준비생이나 아키텍처 감각을 기르고 싶은 중급 개발자에게 잘 맞습니다. 저자의 한 줄 요약이 이 저장소의 성격을 가장 잘 압축합니다.

코드는 컴퓨터에게 무엇을 할지 알려주고, 아키텍처는 그 일이 할 가치가 있는지, 해낼 수 있는지, 버틸 수 있는지를 결정한다.