Community코딩 & 개발github.com

소프트웨어 아키텍처 엔지니어링

코딩 스킬입니다. 아키텍처 무결성을 지속적으로 유지하면서 소프트웨어를 설계, 구현, 리팩토링 및 검토합니다. AI 지원 코딩, 리포지토리 변경, 기능 개발, API/데이터베이스 변경, 모듈 경계, 시스템 설계, 마이그레이션, 배포 선택, 확장성, 신뢰성 및 아키텍처 검토에 사용합니다. 코드를 변경하기 전에 기존 아키텍처를 분석하고, 상황에 가중치를 둔 트레이드오프를 선택하며, 변경 후 아키텍처 제약 조건을 검증합니다. 고립된 저위험 편집에는 가볍게 유지합니다.

소프트웨어 아키텍처 엔지니어링란 무엇인가요?

이 스킬은 AI 에이전트가 코드를 변경하는 동안에도 소프트웨어 아키텍처의 일관성을 유지하도록 설계된 운영 스킬입니다. *소프트웨어 아키텍처의 기초* 2판(Richards & Ford, 2025)의 원칙을 기반으로 하지만, 특정 모델, 언어, 호스트 또는 도구를 요구하지 않습니다. 세 가지 핵심 법칙을 따릅니다. (1) 모든 것은 트레이드오프이며 상황에 따라 평가되어야 하고, (2) 이유(왜)가 방법(어떻게)보다 중요하며, (3) 결정은 이진법이 아닌 스펙트럼 상에 있습니다. 작업의 영향에 따라 Light(가벼움), Standard(표준), Deep(심층) 모드 중에서 노력을 선택하며, 변경 전에 기존 시스템을 발견하고 영향 평가, 경계 보존, 안전한 증분 구현, 기능뿐 아니라 아키텍처 피트니스 함수 검증, 그리고 중요한 결정에 대한 ADR(아키텍처 결정 기록) 작성을 수행하는 6단계 코딩 에이전트 루프를 제공합니다. 또한 설계 전용 및 감사 작업을 지원하며, 검증되지 않은 사실이나 거짓된 보편성(예: 마이크로서비스가 항상 좋음), 숨은 결합도, 위험 무시, 절차적 쇼(체크리스트만 통과)를 금지하는 비협상 가능한 안전장치를 포함합니다. Cursor, Codex, Claude Code 등 모든 AI 코딩 에이전트와 함께 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/iAmSerathion/Skills/tree/HEAD/software-architecture-engineering

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

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

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

문서

소프트웨어 아키텍처 엔지니어링은(는) 무엇을 하나요?

목적

소프트웨어가 변경되는 동안, AI 에이전트가 작성한 변경을 포함하여 아키텍처의 일관성을 유지합니다. 이는 모든 프로젝트를 재설계하라는 명령이 아닌 운영 스킬입니다. 재사용 가능한 원칙은 소프트웨어 아키텍처의 기초, 2판(Richards and Ford, 2025)에서 비롯되었습니다. 지속적인 에이전트 워크플로와 아티팩트는 원본 확장입니다. 특정 모델, 프로그래밍 언어, 리포지토리 호스트, CI 도구 또는 프레임워크가 필요하지 않습니다.

세 가지 법칙을 지속적으로 적용합니다.

  1. 모든 것은 트레이드오프입니다. 실제 맥락에 따라 가중치를 부여하여 비용과 이점을 모두 평가하고, 조건이 변경되면 재평가합니다.
  2. 이유(왜)가 방법(어떻게)보다 중요합니다. 다이어그램과 코드뿐만 아니라 근거, 기각된 옵션, 위험 및 결정 소유자를 보존합니다.
  3. 결정은 스펙트럼 상에 있습니다. 거짓된 이진법, 포괄적인 마이크로서비스 규칙 및 아키텍처 유행을 거부합니다.

영향에 따른 노력 선택

모드일반적인 트리거조치 및 예상 출력
Light (가벼움)고립된 버그, 포맷팅, 계약/경계 영향이 없는 로컬 구현관련 코드와 제약 조건을 검사하고, 최소한의 변경을 수행하며, 관련 검사를 실행하고, 중요한 문제만 보고합니다. 필수 ADR 없음.
Standard (표준)모듈 간 기능, 새 통합, API/스키마 변경, 결과적인 리팩터프로젝트 컨텍스트를 설정하고, 종속성을 검사하며, 현실적인 옵션을 비교하고, 증분 방식으로 구현하며, 경계와 계약을 검증하고, 중요한 결정을 기록합니다.
Deep (심층)새 플랫폼, 서비스 분할, 주요 마이그레이션, 고위험 데이터/보안/신뢰성 변경, 아키텍처 검토전체 컨텍스트 및 아키텍처 분석, 대안, 명시적 데이터/실패 모드, 마이그레이션 및 롤백, 측정 가능한 피트니스 함수, ADR, 위험 및 승인 경계.

에스컬레이션: 작은 편집으로 보였던 것이 소유권 경계를 넘거나, 공개 계약을 변경하거나, 지속성을 변경하거나, 새로운 런타임/배포 구성 요소를 도입하거나, 실패 영향을 확대하거나, 아키텍처 드리프트를 드러낼 때. 데스컬레이션: 조사 결과 아키텍처에 의미 있는 영향이 없는 것으로 나타나면. 사용자/프로젝트/안전 지침이 우선합니다. 사소한 작업에 대해 무거운 보고서를 강제로 작성하지 마십시오.

필수 코딩 에이전트 루프

기존 리포지토리에서 작업할 때 이 루프를 수행하십시오. 정확한 절차, 실패 처리 및 병렬 에이전트 규칙은 에이전트 구현 거버넌스를 참조하십시오.

0. 현재 시스템을 발견하십시오—발명하지 마십시오

  • 액세스 가능한 경우 관련 코드, 테스트, 패키지/빌드 파일, 인프라, 구성, 문서, ADR, 디렉토리 레이아웃 및 실제 종속성 경로를 검사하십시오.
  • 프로젝트 아키텍처 계약(예: docs/architecture/CONTRACT.md) 및 승인된 ADR을 찾고, 이를 프로젝트 제약 조건(불변의 진리가 아님)으로 취급하십시오.
  • 관찰됨 / 제공됨 / 가정됨 / 알 수 없음을 별도로 기록하십시오. 코드 또는 도구에 액세스할 수 없으면 결과가 검증된 리포지토리 분석이 아닌 제안임을 명시하십시오.
  • 이미 사용 중인 아키텍처를 선호하는 스타일로 조용히 대체하지 마십시오.

1. 편집 전에 영향을 평가하십시오

  • 변경 범위, 영향을 받는 비즈니스 기능, 소유자 모듈, API/계약, 데이터 책임, 종속성, 보안 경계, 배포 단위 및 실패 경로를 정의하십시오.
  • 작업을 Light / Standard / Deep으로 분류하고 가장 작은 적절한 검토를 선택하십시오.
  • 중요한 결정의 경우, 범위, 목표 및 측정 방법과 함께 몇 가지 우선순위가 지정된 아키텍처 특성(예: 보안, 지연 시간, 가용성, 확장성, 탄력성, 유지보수성, 테스트 용이성, 배포 용이성, 복구 가능성, 비용)을 도출하십시오. 명시적 요구 사항을 암시적이고 확인되지 않은 요구 사항과 분리하십시오.
  • 저위험 불확실성에 대해 최소한의 되돌릴 수 있는 기본값을 선택하십시오. 지원되지 않는 고위험 가정을 확인된 것처럼 진행하지 마십시오.

2. 경계를 보존하고 필요한 경우 대안을 비교하십시오

  • 높은 응집력과 낮은 결합도를 선호하십시오. 비즈니스 책임, 종속성 방향, 시간적 결합 및 데이터 소유권을 명시적으로 유지하십시오. 논리적 모듈과 독립적으로 배포된 서비스를 구분하십시오.
  • 디렉토리 구조뿐만 아니라 운영 및 데이터 아키텍처에 대한 영향을 확인하십시오. 공유 데이터베이스, 트랜잭션 경계 또는 동기 호출은 명백한 모듈성을 무너뜨릴 수 있습니다.
  • 결과를 초래하는 변경의 경우, 맥락에 가중치를 둔 트레이드오프를 사용하여 최소한 두 가지 실현 가능한 옵션을 비교하십시오. 후보에는 계층형, 모듈형 모놀리스, 파이프라인, 마이크로커널, 서비스 기반, 이벤트 기반, 공간 기반, 오케스트레이션 기반 SOA, 마이크로서비스 또는 하이브리드가 포함될 수 있습니다. 어떤 아키텍처 스타일도 보편적인 기본값이 아닙니다.
  • 분산 설계는 해당되는 경우 네트워크 실패/지연 시간, 가용성, 일관성, 트랜잭션 경계, 재시도, 멱등성, 관찰 가능성, 보안 및 운영 비용을 처리해야 합니다.
  • 결정을 되돌릴 조건의 이름을 지정하십시오. 스타일, 분산 설계 및 기초를 선택적으로 사용하십시오.

3. 안전한 증분 방식으로 구현을 계획하십시오

  • 예상되는 파일/모듈 변경, 안정적으로 유지되어야 하는 계약, 마이그레이션 순서 및 필요한 경우 롤백 전략을 식별하십시오.
  • 아키텍처 불변 항목(항상 참이어야 하는 규칙): 허용된 종속성 방향, 내부 API 소유권, 데이터 쓰기 권한, 테넌시/인증 경계, 하위 호환성, 오류 처리 등을 명시하십시오.
  • 구현 전에 해당 불변 항목에 대한 객관적인 검사를 선택하십시오. 유용한 경우 프로젝트 아키텍처 계약 및 변경 영향 템플릿을 복사/적응하십시오. 허가 없이 또는 명확한 작업 범위 없이 프로젝트 파일을 생성하지 마십시오.
  • 인간/비즈니스 권한이 필요한 되돌릴 수 없거나 영향이 큰 결정을 요청하거나 연기하십시오. 승인을 위조하지 마십시오.

4. 아키텍처 드리프트 없이 구현하십시오

  • 현재 아키텍처와 일관된 가장 작은 변경을 수행하십시오. 입증된 필요 없이 서비스를 분할하거나, 브로커, 전역 추상화 또는 새 프레임워크를 도입하지 마십시오.
  • 인터페이스와 데이터 소유권을 명시적으로 유지하십시오. 다른 모듈의 내부를 우회하거나, 인증/검증을 우회하거나, 이벤트 스키마를 조용히 변경하거나, 관련 없는 변경을 혼합하지 마십시오.
  • 구현 중 계획의 중대한 결함이 드러나면, 중단하고 영향을 받는 결정을 재평가하십시오. 우회 코드로 숨기지 마십시오. 정당한 경우에만 ADR/계약을 업데이트하십시오.
  • 다중 에이전트 작업에서는 구성 요소/파일 소유권, 안정적인 계약 및 통합 소유자를 정의하십시오. 병렬 변경은 공유 아키텍처 제약 조건을 재정의하지 않습니다.

5. 기능뿐만 아니라 아키텍처도 검증하십시오

  • 사용 가능하고 권한이 있는 경우 관련 기존 단위/통합/계약 테스트 및 빌드 검사를 실행하십시오.
  • 아키텍처별 피트니스 함수를 검증하십시오: 금지된 종속성, 순환 참조, 모듈 소유권, API 호환성, 스키마 마이그레이션, 멱등성, 성능 예산, 관찰 가능성, 복원력, 보안, 배포/롤백(해당되는 경우).
  • 변경 전후의 종속성 구조와 영향을 받는 불변 항목을 비교하십시오. 선택적 stdlib 임포트 경계 검사기와 샘플 구성은 선택된 Python/JS/TS 임포트 규칙을 강제 적용할 수 있습니다. 의도적으로 제한적이며 전체 아키텍처 정확성을 증명하지는 않습니다.
  • 증거에 PASS / FAIL / NOT RUN / NOT APPLICABLE 레이블을 지정하십시오. 실제 실행/증거 없이 테스트, 확장성, 프로덕션 준비 상태, 보안 또는 배포가 검증되었다고 주장하지 마십시오.
  • 필수 게이트가 실패하면 수정/되돌리거나, 해결되지 않은 문제와 결정 소유자를 명시적으로 식별하십시오. 실패한 게이트를 완료된 작업으로 제시하지 마십시오.

6. 중요한 결정을 기록하고 전달하십시오

  • 아키텍처적으로 중요한 변경에 대해서만 간결한 ADR을 생성하거나 업데이트하십시오: 제목, 상태, 맥락, 선택된 솔루션, 이유, 대안, 트레이드오프, 결과, 강제 및 재검토 트리거. ADR 템플릿을 사용하십시오.
  • 대체된 경우에도 과거 결정을 보존하십시오. 다이어그램을 구현 또는 검증의 증거가 아닌 커뮤니케이션 지원 도구로 취급하십시오.
  • 최종 보고에서 다음을 명시하십시오: 변경 사항; 아키텍처 영향; 통과, 실패 또는 실행되지 않은 검사; 미해결 위험; 필요한 인간의 결정. Light 변경의 경우 일반적으로 한 단락으로 충분합니다.

설계 전용 및 감사 작업

리포지토리를 편집하지 않을 때는 0-3단계와 6단계를 비례적으로 적용하고, 아무것도 구현되거나 테스트되지 않았다고 가장하지 않고 설계, 트레이드오프 분석, 아키텍처 브리핑 또는 검토를 생성하십시오. 전체 아키텍처 감사의 경우 구성 요소, 데이터 소유권, 경계, 배포 및 팀/인프라 제약 조건을 인벤토리화하고, 증거와 함께 구체적인 위험을 평가하며, 전면 재작성을 권장하기 전에 증분 수정 및 피트니스 함수를 제안하십시오.

비협상 가능한 안전장치

  • 검증 불가능한 사실 금지: 발명된 리포지토리 검사, 테스트 출력, 로드 수준, 규정 준수 상태, 이해관계자 승인 또는 측정값이 없습니다.
  • 거짓된 보편성 금지: 마이크로서비스, 모놀리스 또는 이벤트 기반 시스템이 본질적으로 최고는 아닙니다. 테이블/엔티티만으로 서비스를 분할하지 마십시오.
  • 범위 혼동 금지: 논리적 모듈, 배포 단위, 데이터 소유권 및 아키텍처 특성 범위는 서로 다른 개념입니다.
  • 숨은 결합도 금지: 공유 스키마, 공유 라이브러리, 시간적 결합, 서비스 간 호출 및 이벤트 계약을 검사하십시오. 휘발성 도메인 로직을 재사용하면 결합도가 증가할 수 있습니다.
  • 위험 지우기 금지: 분산 일관성, 트랜잭션 처리, 스키마 변경, 장애 복구 및 롤백은 관련된 경우 명시적인 고려가 필요합니다.
  • 절차적 쇼 금지: 완료된 체크리스트 또는 자체 평가는 증거가 아닙니다. 실제 검사 및 코드 증거를 우선시하십시오.
  • 암묵적 아키텍처 변경 금지: 중요한 편차를 표시하고, 이유를 문서화하며, 책임을 인간/프로젝트 결정 소유자에게 유지하십시오.
  • 저작권이 있는 책 배포 금지: 이 스킬은 원본 종합입니다. 책이나 다이어그램을 다운스트림 리포지토리에 복사하지 마십시오.

필요 시 참조 파일

작업에 필요한 파일만 읽으십시오(이 스킬 디렉토리 기준 상대 경로):

아티팩트: 아키텍처 브리핑, 아키텍처 계약, 변경 영향, ADR, 트레이드오프 매트릭스, 위험 레지스터, 아키텍처 검토, 경계 정책 예제. 작업 시나리오: 경계 드리프트 없는 AI 코딩. 다른 모델/런타임 지침은 선택 사항입니다. 이식성을 참조하십시오.

관련 스킬