architecture-decision-records

architecture-decision-records 스킬 개요

architecture-decision-records 스킬이 하는 일

architecture-decision-records 스킬은 에이전트가 코딩 세션 중에 실제 아키텍처 선택을 가벼운 ADR로 정리하도록 돕습니다. 일이 끝난 뒤 막연한 요약을 쓰게 하는 대신, 결정 지점을 포착하고 맥락과 트레이드오프를 함께 기록해 저장소 안에서 계속 살아 있는 구조화된 기록으로 남기도록 설계되어 있습니다.

Technical Writing과 엔지니어링 팀에 특히 잘 맞는 경우

AI 보조 개발을 하는 팀, 오래 남을 의사결정 이력을 원하는 테크 리드, 시스템 문서의 원천 자료가 필요한 Technical Writing 워크플로에 잘 맞습니다. 이 스킬의 진짜 목적은 “마크다운을 쓰는 것”이 아니라, 팀이 한 방식을 다른 방식보다 왜 택했는지 그 이유가 채팅, 커밋, 기억 속으로 사라지기 전에 보존하는 데 있습니다.

일반적인 프롬프트와 다른 점

일반 프롬프트로도 ADR 템플릿을 한 번 만들 수는 있습니다. 하지만 architecture-decision-records 스킬은 프레임워크 선택, API 패턴, 데이터 저장 방식, 배포 설계, 폐기 결정처럼 세션마다 반복해서 의사결정이 일어날 때 더 유용합니다. 이 스킬의 차별점은 활성화 로직과, Michael Nygard 스타일을 바탕으로 한 일관된 경량 ADR 구조에 있습니다.

도입 전에 알아둘 핵심 주의사항

이 스킬은 의도적으로 범위가 좁습니다. 아키텍처 리뷰, 거버넌스, 저장소별 표준을 대신하지는 못합니다. 또 보이는 구성만 보면 보조 스크립트나 검증 도구 없이 SKILL.md 하나만 제공되는 형태일 가능성이 높아서, 출력 품질은 프롬프트 품질과 저장소 관례에 크게 좌우됩니다.

architecture-decision-records 스킬 사용 방법

설치 맥락과 먼저 읽을 곳

architecture-decision-records 설치를 진행할 때는 Claude Code skills 워크플로에 상위 스킬 컬렉션을 추가한 뒤, skills/architecture-decision-records/SKILL.md를 가장 먼저 여세요. 눈에 보이는 rules/, resources/, 자동화 파일은 없으므로 실제로 쓸 수 있는 안내는 거의 모두 이 한 파일에 들어 있습니다. 읽는 순서는 When to Activate, ADR Format, 그다음 마크다운 펜스 안의 예시 순서가 가장 좋습니다.

스킬이 잘 작동하려면 필요한 입력

architecture-decision-records 스킬은 다음 정보를 주면 가장 잘 동작합니다.

• 어떤 결정을 내리는 중인지
• 실제로 진지하게 검토한 대안들
• 비용, 성능, 팀 숙련도, 마감일, 규정 준수, 마이그레이션 리스크 같은 제약
• 누가 결정했는지와 현재 상태(proposed, accepted, deprecated, superseded)
• ADR을 저장할 위치, 파일명 규칙, 번호 체계

약한 입력: “Postgres 사용에 대한 ADR을 써줘.”
강한 입력: “트랜잭션 주문 처리를 위해 DynamoDB 대신 Postgres를 선택하는 ADR-0012를 작성해줘. 맥락: 다중 행 일관성, 기존 SQL 숙련도, 중간 규모, AWS 배포, 3개월 납기. 상태는 accepted. 결정 참여자: 플랫폼 리드, 백엔드 리드.”

거친 목표를 강한 호출 프롬프트로 바꾸는 법

실무에서 architecture-decision-records를 쓸 때는 추출과 서식을 함께 요청하는 편이 좋습니다. 좋은 프롬프트 패턴은 다음과 같습니다.

“architecture-decision-records 스킬을 사용해줘. 이 대화에서 ADR을 만들어야 하는지 판단해줘. 필요하다면 Michael Nygard 스타일로 Context, Decision, Alternatives Considered를 포함해 초안을 작성하고, 최종 확정 전에 부족한 정보도 함께 표시해줘.”

이 표현이 중요한 이유는, 이 스킬이 결정이 아직 형성되는 단계에서 가장 잘 작동하기 때문입니다. 에이전트가 결정 지점을 포착하고, ADR 초안을 만들고, 근거를 지어내지 않은 채 빠진 정보를 드러내게 해줍니다.

실제 저장소에서 권장하는 작업 흐름

1. 계획 단계나 구현 중에 의미 있는 결정을 포착합니다.
2. 에이전트에게 architecture-decision-records 스킬을 사용해 ADR 초안을 작성하라고 요청합니다.
3. 특히 반대 대안과 제약이 사실과 맞는지 검토합니다.
4. docs/adr/ 또는 adr/처럼 안정적인 폴더에 저장합니다.
5. PR, 아키텍처 문서, 온보딩 문서에서 해당 ADR로 연결합니다.

Technical Writing에서는 ADR에 짧은 “impact” 메모를 함께 붙이면 좋습니다. 독자가 이제 API, 인프라, 향후 마이그레이션에 대해 무엇을 전제로 해야 하는지 적어두는 방식입니다. 그러면 ADR이 엔지니어링 채팅 기록을 넘어 더 재사용 가능한 자료가 됩니다.

architecture-decision-records 스킬 FAQ

이미 ADR을 프롬프트로 만들 수 있는데, architecture-decision-records를 설치할 가치가 있나요?

있습니다. 문제의 핵심이 마크다운 서식이 아니라 일관성과 타이밍이라면 더욱 그렇습니다. architecture-decision-records 스킬은 결정이 발생한 바로 그 시점에 기록하도록 에이전트의 트리거를 더 분명하게 만들어 줍니다. 일회성 ADR 템플릿만 필요하다면 일반 프롬프트로도 충분할 수 있습니다.

초보자에게도 괜찮나요?

괜찮습니다. 다만 한 가지 조건이 있습니다. 초보자도 유용한 ADR 초안을 받을 수 있지만, 어떤 제약이 중요한지 또는 어떤 대안이 실제로 가능한지는 스스로 잘 모를 수 있습니다. 이 스킬은 생각을 구조화해 주지만, 수락 전에 기술적 트레이드오프를 검토하는 일은 여전히 리뷰어의 몫입니다.

언제 이 스킬을 쓰지 말아야 하나요?

사소한 구현 세부사항, 잠깐 해보는 실험, 아키텍처에 장기적인 영향이 없는 결정에는 쓰지 않는 것이 좋습니다. 기록이 과해지면 ADR 노이즈만 늘어납니다. 앞으로 유지보수자가 “왜 이 스택, 이 패턴, 이 경계, 이 연동 방식을 택했지?”라고 물을 만한 선택에만 architecture-decision-records를 사용하세요.

Technical Writing 작업에는 어떻게 맞물리나요?

architecture-decision-records 스킬은 근거를 원천에 가장 가깝게 남겨 준다는 점에서 Technical Writing에 유용합니다. 작가는 수락된 ADR을 바탕으로 흩어진 채팅이나 PR 코멘트를 다시 맞추지 않고도 시스템 개요, 마이그레이션 노트, FAQ, 온보딩 자료로 발전시킬 수 있습니다.

architecture-decision-records 스킬 개선 방법

주제만 주지 말고, 더 나은 원천 자료를 주세요

품질을 가장 크게 좌우하는 것은 구체성입니다. 제약, 배제한 옵션, 실제로 결정을 밀어붙인 요인을 함께 넣으세요. “캐싱용으로 Redis를 선택했다”는 약합니다. “공유 무효화가 워커 전반에 필요하고 수평 확장 시 동작을 예측 가능하게 유지해야 해서, 인프로세스 캐싱보다 Redis를 선택했다”는 훨씬 낫습니다. architecture-decision-records 스킬은 이미 입력된 근거만 보존할 수 있습니다.

흔한 실패 모드를 막는 법

자주 생기는 문제는 흐릿한 맥락, 가짜 대안, 과도하게 자신 있는 결론입니다. 초안이 마치 결정이 처음부터 자명했던 것처럼 읽히면, 에이전트에게 트레이드오프를 더 자세히 풀어 달라고 하세요. 대안이 피상적이라면 실제로 논의한 상위 2~3개 옵션을 직접 알려주세요. 결정이 아직 잠정적이면 억지로 accepted로 밀어붙이지 말고 proposed 상태를 유지하세요.

저장소 표준에 맞게 ADR 출력을 조정하세요

상위 스킬은 경량 ADR 구조를 사용하지만, 많은 팀은 consequences, links, owners, review date 같은 추가 필드를 필요로 합니다. 저장소에서 어떤 헤딩이 필수인지, 파일을 어디에 둘지 명확히 지시해 architecture-decision-records 사용을 개선하세요. 그렇지 않으면 초안은 깔끔해도 결국 서식 손질이 다시 필요할 수 있습니다.

첫 초안 이후에 반복 개선하세요

첫 출력은 최종 진실이 아니라 의사결정 점검선으로 보세요. 다음과 같이 후속 질문을 던지면 좋습니다.

• “이 ADR에서 명시되지 않은 가정은 무엇인가?”
• “어느 대안을 더 공정하게 다뤄야 하나?”
• “나중에 되돌릴 때의 신호를 무엇으로 기록해야 하나?”
• “어떤 코드 영역이나 문서가 이 ADR로 연결되어야 하나?”

이런 후속 질문은 architecture-decision-records 스킬을 단순한 템플릿 채우기보다 훨씬 가치 있게 만듭니다. 특히 몇 달 뒤에도 여전히 유용한 ADR을 원할 때 효과가 큽니다.