architecture-decision-records

개요

architecture-decision-records는 팀이 중요한 기술 및 아키텍처 결정을 Architecture Decision Records(ADRs)를 통해 문서화, 추적, 검토할 수 있도록 돕는 프로젝트 관리 스킬입니다. 이 스킬은 소프트웨어 프로젝트에서 주요 선택의 배경, 이유, 결과를 명확하게 기록할 수 있는 패턴과 템플릿을 제공합니다. 투명한 의사결정 프로세스를 구축하고 온보딩 및 향후 참조를 위한 기록을 유지하려는 엔지니어링 팀, 기술 리드, 프로젝트 매니저에게 적합합니다.

architecture-decision-records가 해결하는 문제

• 중요한 기술 결정을 문서화하고 쉽게 접근할 수 있도록 보장
• 과거 아키텍처 선택을 검토하고 그 영향을 이해하는 데 도움
• 특정 결정이 내려진 배경을 제공하여 온보딩 지원
• ADR 기록 및 관리 프로세스 표준화

이 스킬을 사용해야 하는 대상

• 중요한 아키텍처 또는 기술 선택을 하는 팀
• 기술 문서화와 의사결정 투명성을 개선하려는 조직
• 설계 트레이드오프와 이유를 장기적으로 추적해야 하는 프로젝트

사용 방법

설치 단계

1. 다음 명령어로 프로젝트에 스킬을 추가하세요:

   npx skills add https://github.com/wshobson/agents --skill architecture-decision-records

2. 설치 후, SKILL.md 파일을 읽어 워크플로우와 모범 사례를 먼저 확인하세요.

ADR 시작하기

• SKILL.md에 포함된 템플릿과 안내를 검토하여 ADR 구조를 이해하세요.
• 표준 ADR 형식을 사용해 다음을 기록하세요:
  • 배경(Context): 결정이 필요한 이유
  • 결정(Decision): 내린 결정 내용
  • 결과(Consequences): 영향과 결과
• ADR은 리포지토리 내 전용 폴더(예: /docs/adr/)에 보관하세요.

워크플로우 맞춤화

• 팀의 필요, 도구, 리포지토리 구조에 맞게 템플릿과 프로세스를 조정하세요.
• ADR 수명 주기(제안됨 → 승인됨 → 폐기됨 → 대체됨)를 활용해 각 결정 상태를 관리하세요.

검토할 주요 파일

• SKILL.md – 주요 가이드 및 워크플로우
• README.md, AGENTS.md 및 추가 컨텍스트를 위한 지원 폴더(존재하는 경우)

자주 묻는 질문

architecture-decision-records로 언제 ADR을 작성해야 하나요?

새 프레임워크 도입, 데이터베이스 기술 선택, API 설계 등 중요한 아키텍처나 기술 결정을 할 때 ADR을 작성하세요. 일상적인 유지보수, 소규모 업그레이드, 버그 수정은 일반적으로 ADR이 필요하지 않습니다.

architecture-decision-records가 권장하는 형식은 무엇인가요?

이 스킬은 배경, 결정, 결과를 담는 표준 ADR 템플릿(MADR 형식)을 제공합니다. 프로젝트에 맞게 템플릿을 조정할 수 있습니다.

ADR은 프로젝트 내 어디에 보관해야 하나요?

ADRs는 일반적으로 리포지토리 내 /docs/adr/ 또는 /architecture/decisions/ 같은 전용 폴더에 보관하여 접근성과 버전 관리를 용이하게 합니다.

이 스킬이 프로젝트 관리에 어떻게 도움이 되나요?

결정과 그 이유를 문서화함으로써 architecture-decision-records는 기술 팀의 투명성, 온보딩, 장기 유지보수를 향상시킵니다.

더 많은 세부 정보나 템플릿은 어디서 찾을 수 있나요?

스킬 디렉토리의 Files 탭을 열어 architecture-decision-records에 포함된 모든 템플릿, 참고 자료, 도우미 스크립트를 확인하세요.