Communitygithub.com

renatoxm/leanagentkit

GitHub Spec Kit의 간소화된 대안

leanagentkit란 무엇인가요?

이 스킬은 소프트웨어 아키텍처에서 비즈니스 규칙이 프레임워크, 데이터베이스 및 전송 메커니즘으로부터 독립성을 유지하도록 구조화하는 클린 아키텍처 프레임워크를 제시합니다. 의존성 규칙(Dependency Rule)을 핵심 원칙으로 삼아 소스 코드 의존성이 항상 고수준 정책(내부 원)을 향하도록 강제합니다. 이 원칙을 통해 시스템은 테스트 가능성, 프레임워크·UI·데이터베이스 독립성을 확보하고, 비즈니스 로직을 고립된 상태에서 검증할 수 있습니다. Claude Code, Cursor, Codex 등 AI 어시스턴트가 아키텍처 검토, 모듈 경계 설계, 의존성 관리 조언 시 이 원칙을 적용할 수 있도록 설계되었습니다. 각 하위 원칙(Entities/Use Cases, Interface Adapters, Component Principles, SOLID, Boundaries)은 왜 동작하는지, 핵심 통찰, 코드 적용 예시, 그리고 참조 문서 링크로 상세히 설명됩니다. 또한 7가지 Quick Diagnostic 질문을 통해 현재 아키텍처의 점수를 산출하고, 실패한 항목에 대한 구체적인 개선 방향을 제시합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add renatoxm/leanagentkit

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

클린 아키텍처 프레임워크

비즈니스 규칙이 프레임워크, 데이터베이스, 전송 메커니즘과 무관하게 독립성을 유지하도록 소프트웨어를 구조화하는 훈련된 접근 방식입니다. 시스템 아키텍처를 설계하거나, 모듈 경계를 검토하거나, 의존성 관리에 대해 조언할 때 이 원칙을 적용하십시오.

핵심 원칙

소스 코드 의존성은 반드시 안쪽(고수준 정책)을 가리켜야 합니다. 내부 원에 있는 어떤 것도 외부 원에 대해 알 수 없습니다. 이 단일 규칙은 테스트 가능하고 프레임워크, UI, 데이터베이스 및 모든 외부 요소로부터 독립적인 시스템을 만듭니다. 비즈니스 규칙이 중요합니다. 데이터베이스, 웹 프레임워크, 전송 메커니즘은 세부사항일 뿐입니다. 세부사항이 정책에 의존하면 결정을 미루고, 구현을 교체하며, 비즈니스 로직을 고립된 상태에서 테스트할 수 있습니다.

점수

목표: 10/10. 아키텍처가 충족하는 일곱 가지 Quick Diagnostic 행 각각에 대해 1점을 부여하고(0-7), 이를 0-10 구간으로 매핑합니다. 6-7개 충족 = 9-10 (의존성 규칙 준수, 비즈니스 로직이 프레임워크 및 DB와 독립적); 4-5개 = 6-8 (핵심은 테스트 가능하지만 일부 세부사항이 안쪽으로 누출됨); 2-3개 = 3-5 (프레임워크나 영속성이 구조를 지배함); 0-1개 = 0-2 (경계 없음 — 비즈니스 규칙이 컨트롤러와 ORM 모델에 존재). 점수, 실패한 진단 행, 그리고 각각을 수정하기 위해 필요한 구체적인 역전 방향을 보고하십시오.

1. 의존성 규칙과 동심원

핵심 개념: 아키텍처를 동심원으로 구성합니다. 가장 안쪽에 엔터티(엔터프라이즈 비즈니스 규칙), 그 다음에 유스 케이스(애플리케이션 비즈니스 규칙), 그 다음에 인터페이스 어댑터, 가장 바깥쪽에 프레임워크 및 드라이버를 배치합니다. 소스 코드 의존성은 항상 안쪽을 가리킵니다.

왜 동작하는가: 고수준 정책이 저수준 세부사항에 의존하지 않으면 비즈니스 로직을 건드리지 않고 데이터베이스, 웹 프레임워크, API 스타일을 교체할 수 있습니다. 시스템은 스택에서 가장 변동성이 큰 부분에 탄력적으로 대응하게 됩니다.

핵심 통찰:

  • 내부 원은 외부 원의 이름을 언급할 수 없습니다. 외부의 클래스, 함수, 변수, 데이터 형식을 사용할 수 없습니다.
  • 경계를 넘는 데이터는 내부 원에 가장 편리한 형태여야 하며, 외부 원이 강요해서는 안 됩니다.
  • 의존성 역전(인터페이스는 안쪽에서 정의되고 바깥쪽에서 구현됨)이 규칙을 강제하는 메커니즘입니다.
  • 원의 개수는 고정되어 있지 않습니다. 일반적으로 네 개이며, 규칙은 동일하게 유지됩니다.
  • 프레임워크는 세부사항이지 아키텍처가 아닙니다. 가장 바깥쪽 원에 속합니다.

코드 적용:

맥락패턴예시
레이어 방향내부 원이 인터페이스를 정의하고 외부가 구현UserRepository 인터페이스는 유스 케이스에; PostgresUserRepository는 어댑터에
데이터 교차DTO가 경계를 넘고 ORM 엔터티는 넘지 않음유스 케이스는 UserResponse DTO를 반환하고, ActiveRecord 모델은 반환하지 않음
의존성 방향임포트 화살표는 항상 안쪽을 가리킴컨트롤러가 유스 케이스를 임포트; 유스 케이스는 컨트롤러를 임포트하지 않음

내부 원 임포트가 바깥쪽을 가리킬 때 네 원 코드 설명, 데이터 교차 규칙, 그리고 이를 수정하기 위한 네 단계 의존성 역전 절차를 확인하려면 references/dependency-rule.md를 참조하십시오.

2. 엔터티와 유스 케이스

핵심 개념: 엔터티는 엔터프라이즈 전반의 비즈니스 규칙(소프트웨어가 없어도 존재할 규칙)을 캡슐화합니다. 유스 케이스는 엔터티와의 데이터 흐름을 조율하는 애플리케이션 특화 규칙을 포함합니다.

왜 동작하는가: 비즈니스가 수행하는 일(엔터티)과 애플리케이션이 이를 조율하는 방법(유스 케이스)을 분리하면 엔터티를 여러 애플리케이션에서 재사용하고, 핵심 비즈니스 규칙을 변경하지 않고 애플리케이션 동작을 변경할 수 있습니다.

핵심 통찰:

  • 엔터티는 데이터베이스 행이 아닙니다. 중요한 비즈니스 규칙을 캡슐화하는 객체 또는 순수 함수입니다.
  • 유스 케이스는 요청 모델을 받고 응답 모델을 반환합니다. 프레임워크 객체는 절대 사용하지 않습니다.
  • 각 유스 케이스는 단일 애플리케이션 작업입니다(CreateOrder, ApproveExpense).
  • 인터랙터 패턴: 유스 케이스 클래스는 입력 경계 인터페이스를 구현하고 출력 경계 인터페이스를 호출합니다.
  • 유스 케이스의 변경이 엔터티에 영향을 주어서는 안 됩니다. 엔터티 변경은 유스 케이스에 전파될 수 있습니다.

코드 적용:

맥락패턴예시
엔터티 설계중요한 비즈니스 규칙, 프레임워크 의존성 제로Order.calculateTotal()은 세금 규칙을 적용; HTTP에 대해 전혀 알지 못함
요청/응답단순한 데이터 구조가 경계를 넘음CreateOrderRequest { items, customerId } — ORM 모델 없음
단일 책임작업당 하나의 유스 케이스PlaceOrder, CancelOrder, RefundOrder를 별도의 클래스로
인터랙터입력 포트를 구현하고 출력 포트를 호출PlaceOrderInteractor implements PlaceOrderInput

인터랙터를 설계하거나 엔터티와 유스 케이스에 무엇이 속해야 하는지 결정할 때 엔터프라이즈 vs 애플리케이션 비즈니스 규칙에 대한 완전한 설명과 요청/응답 모델 예시를 확인하려면 references/entities-use-cases.md를 참조하십시오.

3. 인터페이스 어댑터와 프레임워크

핵심 개념: 인터페이스 어댑터는 유스 케이스/엔터티에 편리한 형태의 데이터와 외부 기관이 요구하는 형태 간 변환을 수행합니다. 프레임워크와 드라이버는 가장 바깥쪽 계층이며 외부 세계와의 접착 코드입니다.

왜 동작하는가: 웹 프레임워크, ORM, 메시지 큐가 외부 원에 국한되면 이들을 교체하는 것이 국소적인 변경이 됩니다. 데이터베이스는 세부사항이고, 웹은 세부사항입니다. 세부사항은 비즈니스 규칙에 플러그인처럼 연결되어야 하며, 애플리케이션의 뼈대가 되어서는 안 됩니다.

핵심 통찰:

  • 컨트롤러는 HTTP를 유스 케이스 입력으로 변환합니다. 프리젠터는 유스 케이스 출력을 뷰 모델로 변환합니다.
  • 게이트웨이는 유스 케이스가 정의한 리포지토리 인터페이스를 구현합니다. 내부 원이 계약을 정의하고 외부가 이를 충족합니다.
  • 비즈니스 규칙은 데이터가 SQL, NoSQL, 플랫 파일 중 어디에 있는지, 또는 전송이 HTTP인지 결코 알지 못합니다.
  • 프레임워크를 의심하십시오. 프레임워크는 여러분이 결합되기를 원합니다. 팔 길이만큼 거리를 두십시오.

코드 적용:

맥락패턴예시
컨트롤러전달 메커니즘 → 유스 케이스 입력OrderController.create(req)가 CreateOrderRequest를 구성하고 인터랙터 호출
프리젠터유스 케이스 출력 → 뷰 모델OrderPresenter.present(response)를 JSON/HTML 형식으로 변환
게이트웨이DB별로 구현된 리포지토리 인터페이스SqlOrderRepository implements OrderRepository
프레임워크 경계프레임워크가 안쪽을 호출하고, 그 반대는 없음Express 라우트 핸들러가 컨트롤러를 호출; 컨트롤러는 Express를 임포트하지 않음

컨트롤러, 프리젠터, 게이트웨이를 연결하거나 데이터베이스/웹이 세부사항임을 주장할 때 플러그인 아키텍처와 프레임워크를 가장자리로 국한시키는 방법을 확인하려면 references/adapters-frameworks.md를 참조하십시오.

4. 컴포넌트 원칙

핵심 개념: 컴포넌트는 배포 단위입니다. 세 가지 응집 원칙이 컴포넌트 내부의 내용을 규율하고, 세 가지 결합 원칙이 컴포넌트 간의 관계를 규율합니다.

왜 동작하는가: 잘못 구성된 컴포넌트는 하나의 변경이 관련 없는 코드의 재배포를 강제하는 파급 효과를 만듭니다. 원칙은 변경을 국소화하고 릴리스를 독립적으로 유지합니다.

핵심 통찰:

  • REP (재사용/릴리스 등가): 컴포넌트의 클래스는 단위로 버전 관리 및 릴리스가 가능해야 함
  • CCP (공통 폐쇄): 동일한 이유로 동시에 변경되는 클래스는 함께 속함 — 컴포넌트를 위한 SRP
  • CRP (공통 재사용): 사용하지 않는 클래스에 의존하도록 강요하지 말 것
  • ADP (비순환 의존성): 컴포넌트 그래프에 순환이 없어야 함 — DIP 또는 새 컴포넌트로 순환을 끊을 것
  • SDP (안정된 의존성): 안정성 방향으로 의존할 것
  • SAP (안정된 추상화): 안정적인 컴포넌트는 추상적이어야 하고, 불안정한 컴포넌트는 구체적이어야 함

코드 적용:

맥락패턴예시
컴포넌트 그룹화함께 변경되는 클래스 그룹화 (CCP)모든 주문 관련 유스 케이스를 하나의 컴포넌트에
순환 끊기DIP 적용하여 의존성 가장자리 역전인터페이스를 새 컴포넌트로 추출하여 순환 끊기
안정성 메트릭불안정성 I = Ce / (Ca + Ce)많은 수신, 발신 의존성 없음 → I가 0에 가까움 (안정적)

클래스를 배포 가능한 컴포넌트로 그룹화하거나 의존성 순환을 끊을 때, REP, CCP, CRP, ADP, SDP, SAP 각각을 불안정성 메트릭과 함께 확인하려면 references/component-principles.md를 참조하십시오.

5. SOLID 원칙

핵심 개념: 다섯 가지 클래스 및 모듈 수준 원칙 — 단일 책임, 개방-폐쇄, 리스코프 치환, 인터페이스 분리, 의존성 역전 — 의존성 규칙을 가능하게 하는 중간 수준의 구성 요소입니다.

왜 동작하는가: 각 원칙은 의존성이 잘못되는 특정 방식을 다루어, 코드베이스를 레거시 악몽으로 만드는 경직성, 취약성, 부동성을 방지합니다.

핵심 통찰:

  • SRP: 모듈은 변경 이유가 하나여야 함 — 하나의 액터를 제공(단순히 "하나의 일"을 하는 것이 아님)
  • OCP: 기존 코드를 수정하지 않고 새 코드를 추가하여 동작을 확장 — 전략 및 플러그인 패턴
  • LSP: 서브타입은 클라이언트가 알 필요 없이 기본 인터페이스를 통해 사용 가능해야 함 — 예외적인 예외나 무시된 메서드로 위반됨
  • ISP: 클라이언트는 사용하지 않는 메서드에 의존해서는 안 됨 — 거대 인터페이스는 불필요한 결합을 만듦
  • DIP: 고수준 모듈과 저수준 모듈 모두 고수준 모듈이 정의한 추상화에 의존해야 함

코드 적용:

맥락패턴예시
SRP 위반클래스가 여러 액터를 제공Employee가 급여(CFO), 보고(COO), 영속성(CTO) 처리
전략을 통한 OCP새 동작을 새 클래스로 추가ExpressShipping이 ShippingStrategy 구현; Order는 수정되지 않음
LSP 위반서브타입이 예상된 동작 변경Square extends Rectangle이 setWidth()/setHeight() 계약 위반
ISP 적용거대 인터페이스를 역할 인터페이스로 분할하나의 MultiFunctionDevice 대신 Printer, Scanner, Fax
DIP 배선고수준이 인터페이스 정의; 저수준이 구현OrderService는 StripeClient가 아닌 PaymentGateway에 의존

특정 클래스에 SRP/OCP/LSP/ISP/DIP를 적용하거나 위반 사항을 진단할 때, 각 원칙을 코드 예제와 방지하는 악취와 함께 확인하려면 references/solid-principles.md를 참조하십시오.

6. 경계와 경계 해부학

핵심 개념: 경계는 중요한 것과 세부사항 사이의 선으로, 다형성을 통해 구현됩니다. 의존성은 안쪽을 가리키며 교차하고, 제어 흐름은 양방향으로 교차할 수 있습니다.

왜 동작하는가: 모든 경계는 결정을 미루거나 구현을 교체할 수 있는 옵션을 제공합니다. 전략적 경계 배치는 시스템이 수년간 유지 관리하기 즐거운지 고통인지를 결정합니다.

핵심 통찰:

  • 완전한 경계는 양쪽에서 상호 인터페이스를 사용합니다. 부분적 경계는 더 단순한 전략이나 퍼사드를 사용합니다.
  • Humble Object 패턴: 경계 코드를 테스트하기 어려운 부분(경계 근처)과 테스트하기 쉬운 부분(로직)으로 분할합니다.
  • 서비스가 자동으로 아키텍처 경계가 되는 것은 아닙니다. 공유된 거대 데이터 모델을 가진 마이크로서비스는 네트워크 호출이 있는 모놀리스입니다.
  • 테스트는 가장 고립된 컴포넌트입니다. 안쪽에 의존하고, 아무도 테스트에 의존하지 않습니다.
  • 조기 경계는 비용이 많이 들지만, 경계가 없는 것도 마찬가지입니다. 변동 가능성이 있는 지점에 경계를 그리십시오.

코드 적용:

맥락패턴예시
완전 vs. 부분 경계상호 포트, 또는 단일 전략유스 케이스가 PlaceOrderInput/PlaceOrderOutput 정의; 더 단순한 경우 ShippingStrategy 사용
Humble Object테스트 가능한 로직을 인프라에서 분리PresenterLogic(테스트 가능)이 ViewModel 생성; View(humble)가 렌더링
플러그인으로서의 Main구성 루트가 시스템을 조립main()이 모든 구체적 구현을 배선하고 앱 시작

경계를 그릴 위치 결정, 완전 vs. 부분 경계 선택, Humble Object 패턴 적용 시, 서비스를 경계로, 테스트 경계, 그리고 궁극적인 플러그인으로서의 Main을 포함하여 확인하려면 references/boundaries.md를 참조하십시오.

일반적인 실수

실수실패 이유수정
ORM이 비즈니스 로직으로 누출엔터티가 스키마에 결합; DB 변경이 비즈니스 규칙을 재작성도메인 엔터티를 영속성 모델과 분리; 어댑터 계층에서 매핑
컨트롤러의 비즈니스 규칙HTTP 없이 테스트 불가; 엔드포인트 간 중복로직을 유스 케이스 인터랙터로 이동; 컨트롤러는 번역 및 위임만 수행
프레임워크 우선 아키텍처프레임워크가 구조를 결정; 교체 시 재작성 필요프레임워크를 플러그인으로 취급; 코드를 비즈니스 기능별로 구조화
순환 컴포넌트 의존성변경이 예측 불가능하게 파급; 독립적 릴리스 불가DIP 적용 또는 공유 추상화 컴포넌트 추출
기능당 하나의 거대 유스 케이스비대해진 수천 줄의 오케스트레이터집중된 단일 작업 유스 케이스로 분할
"간단하니까" 경계 건너뛰기결합이 조용히 누적되다가 막대한 비용 발생변동 가능성이 있는 지점에 사전에 경계를 그림
마이크로서비스 = 자동으로 좋은 아키텍처분산 모놀리스는 깨끗한 모놀리스보다 더 나쁨서비스 내부와 서비스 간에 의존성 규칙 적용; 서비스는 배포 경계일 뿐, 아키텍처 경계가 아님

빠른 진단

질문아니오인 경우조치
DB, 웹 서버, 프레임워크 없이 비즈니스 규칙을 테스트할 수 있습니까?규칙이 인프라에 결합됨인터페이스 뒤에 엔터티와 유스 케이스 추출; 외부 계층 모킹
모든 소스 의존성이 안쪽을 가리킵니까? (외부 원이 내부 원을 임포트하지 않음)의존성 역전 위반DIP 적용: 내부 원이 소유한 인터페이스에 의존하도록 외부 원 변경
데이터가 경계를 넘을 때 내부 원에 편리한 간단한 구조를 사용합니까?ORM/프레임워크 객체가 안쪽으로 누출됨전용 DTO/요청 모델 도입; 어댑터 계층에서 매핑
유스 케이스가 단일 작업을 수행하고 프레임워크에 독립적입니까?유스 케이스가 여러 책임을 가지거나 프레임워크에 결합됨각 유스 케이스를 단일 작업으로 리팩토링; 프레임워크 임포트 제거
엔터티가 프레임워크/ORM에 대한 의존성 없이 중요한 비즈니스 규칙만 포함합니까?엔터티가 영속성 또는 UI 세부사항과 혼합됨진정한 비즈니스 규칙만 남도록 엔터티에서 인프라 관심사 분리
컴포넌트 의존성 그래프에 순환이 없습니까?순환 존재순환 끊기를 위해 DIP 또는 새 컴포넌트 적용
DB, 웹, 메시징 등을 교체할 때 비즈니스 규칙을 변경해야 합니까?세부사항이 아키텍처를 오염시킴외부 원에 프레임워크/DB 코드 국한; 내부 원은 인터페이스를 통해 통신

참조

  • 의존성 규칙 — 내부 원 임포트가 바깥쪽을 가리킬 때 네 원 코드 설명, 데이터 교차 규칙, 의존성 역전 절차
  • 엔터티 및 유스 케이스 — 엔터프라이즈 vs 애플리케이션 비즈니스 규칙, 요청/응답 모델
  • 어댑터 및 프레임워크 — 컨트롤러, 프리젠터, 게이트웨이, 프레임워크 국한
  • 컴포넌트 원칙 — REP, CCP, CRP, ADP, SDP, SAP, 불안정성 메트릭
  • SOLID 원칙 — SRP, OCP, LSP, ISP, DIP 코드 예제
  • 경계 — 전체/부분 경계, Humble Object, Main을 플러그인으로

관련 스킬