architecture-decision-records

architecture-decision-records 스킬 개요

architecture-decision-records가 실제로 도와주는 일

architecture-decision-records 스킬은 AI 에이전트가 Architecture Decision Record(ADR)를 초안 작성하고, 수정하고, 지속적으로 관리할 때 일반적인 “ADR 하나 써줘” 프롬프트보다 더 명확한 구조로 작업할 수 있게 돕습니다. 이 스킬은 오래 남아도 의미가 유지되는 기술 의사결정 문서가 필요한 팀을 위해 설계되었습니다. 즉, 왜 이 결정이 필요했는지, 무엇을 선택했는지, 어떤 대안을 검토했는지, 그리고 그 결과 어떤 영향이 따르는지를 일관되게 남기는 데 초점이 있습니다.

기술 문서 작성과 엔지니어링 팀에 특히 잘 맞는 경우

이 스킬은 프로젝트마다 일관된 의사결정 기록이 필요한 Technical Writing 담당자, staff engineer, architect, platform team, engineering manager에게 특히 유용합니다. 단순히 “문서 하나 작성”하는 일이 아니라 “나중에 읽는 사람도 신뢰할 수 있도록 판단 근거를 남기는 것”이 목적일 때 가장 잘 맞습니다.

실제로 해결하는 핵심 과제

대부분의 팀은 ADR 제목을 붙이는 데서 막히지 않습니다. 진짜 어려운 지점은 흩어진 배경 정보와 논의를 정리해, 리뷰할 수 있고 서로 비교 가능하며 6개월 뒤에도 가치가 있는 의사결정 기록으로 바꾸는 일입니다. architecture-decision-records 스킬이 유용한 이유는 모호한 아키텍처 메모를 만들어내는 대신, ADR의 핵심 요소인 맥락, 결정, 대안, 결과를 중심에 두기 때문입니다.

일반 프롬프트와 architecture-decision-records 스킬의 차이점

가장 큰 차별점은 구조입니다. 이 스킬은 다음과 같은 ADR 모범 사례를 전제로 설계되어 있습니다.

• 어떤 경우 ADR을 작성할 가치가 있고, 어떤 경우는 과한 절차인지
• proposed, accepted, rejected, deprecated, superseded 같은 일반적인 라이프사이클 상태
• MADR 스타일 같은 표준 템플릿
• 자유 형식 서술이 아니라 결정 중심의 구성

그래서 여러 의사결정을 반복적으로 문서화해야 하고, 문서 품질을 일정하게 유지해야 하는 상황에서는 일반 프롬프트보다 더 적합합니다.

architecture-decision-records가 강력한 선택이 되는 경우

architecture-decision-records 스킬은 다음과 같은 결정에 특히 적합합니다.

• 새로운 framework 또는 platform 도입
• database 또는 messaging system 선정
• API 또는 integration pattern 정의
• security architecture 방향 설정
• 장기적인 영향을 가지는 tradeoff 문서화

반대로 변경 사항이 단순 유지보수, bug fix, 사소한 구현 디테일 수준이라면 이 스킬은 대개 필요한 것보다 절차가 많은 편입니다.

architecture-decision-records 스킬 사용 방법

architecture-decision-records 설치 맥락

이 스킬은 wshobson/agents 저장소의 다음 경로에 있습니다.

plugins/documentation-generation/skills/architecture-decision-records

일반적인 설치 방식은 다음과 같습니다.

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

환경에 따라 다른 skill loader를 쓸 수도 있지만, 핵심은 slug가 architecture-decision-records라는 점입니다.

먼저 읽어야 할 파일

다음 파일부터 확인하세요.

SKILL.md

이 저장소 경로에는 실질적으로 의미 있는 소스 파일이 하나뿐이라, 숨겨진 구현을 따로 뒤져볼 부분이 많지 않습니다. 빠르게 도입하기에는 장점이지만, 그만큼 결과물 품질은 사용자가 제공하는 프롬프트 맥락에 크게 좌우됩니다.

architecture-decision-records가 잘 동작하려면 어떤 입력이 필요한가

architecture-decision-records 스킬은 단순한 주제보다 “의사결정 가능한 입력”이 주어질 때 가장 잘 동작합니다. 에이전트에게 다음 정보를 제공하세요.

• 내려야 할 결정
• 비즈니스 또는 기술적 맥락
• 제약 조건과 non-goals
• 이미 검토한 대안
• 선택 기준
• 알려진 결과나 위험
• 현재 상태: proposed, accepted, rejected, deprecated, 또는 superseded

이 정보가 없더라도 에이전트는 깔끔한 ADR 뼈대를 만들 수는 있습니다. 다만 판단 근거는 일반론적으로 흐를 가능성이 큽니다.

거친 목표를 강한 프롬프트로 바꾸기

약한 프롬프트:

Write an ADR about using PostgreSQL.

더 강한 프롬프트:

Draft an ADR for selecting PostgreSQL as the primary relational database for our B2B SaaS platform. Context: we are replacing a single-tenant MySQL deployment, need strong transactional guarantees, support for JSON columns, and managed cloud hosting. Alternatives considered: MySQL 8, PostgreSQL, CockroachDB. Constraints: team already knows SQL but not distributed SQL operations; must run in AWS; migration must complete within 2 quarters. Include status as Proposed, decision drivers, tradeoffs, consequences, and when this ADR should be revisited.

두 번째 프롬프트는 템플릿에 추측을 덧붙이는 수준이 아니라, 실제 의사결정 기록을 만들 수 있을 만큼 충분한 정보를 제공합니다.

architecture-decision-records 사용을 위한 추천 워크플로

실무적인 architecture-decision-records usage 흐름은 다음과 같습니다.

1. issue thread, RFC, design doc에서 의사결정 관련 사실을 수집합니다.
2. 이 변경이 ADR로 남길 가치가 있는지 판단합니다.
3. 원하는 형식을 지정해 스킬에 ADR 초안을 작성하게 합니다.
4. 빠진 대안, 약한 근거, 모호한 결과가 없는지 리뷰합니다.
5. 리뷰 또는 승인 이후 상태를 업데이트합니다.
6. 결정이 바뀌면 superseding ADR을 연결합니다.

이 스킬이 가장 빛나는 지점은, 원재료처럼 흩어져 있는 결정 정보를 안정적인 문서 형식으로 압축해 주는 부분입니다.

초안 작성 전에 템플릿부터 정하기

원본은 표준 ADR 접근과 MADR 스타일 템플릿을 함께 강조합니다. 프롬프트를 쓰기 전에 다음 중 어떤 형식을 원하는지 먼저 정하세요.

• 간결한 표준 ADR
• 대안과 결과를 명시하는 MADR 유사 구조
• 팀 저장소에 맞춘 house style

팀에서 이미 ADR 번호 체계나 고정된 heading 순서를 쓰고 있다면, 이를 처음부터 스킬에 알려주는 것이 좋습니다. 그렇지 않으면 ADR 자체는 타당하게 나와도 수작업으로 다시 맞춰야 할 수 있습니다.

Technical Writing 용도로 쓸 때 포함하면 좋은 것

architecture-decision-records for Technical Writing 용도라면, 승인자만이 아니라 미래의 독자를 기준으로 최적화해 달라고 요청하세요. 다음 항목을 추가하면 좋습니다.

• 약어는 처음 한 번 풀어서 정의하기
• context와 decision driver를 분리하기
• 기각된 옵션이 왜 기각됐는지 설명하기
• 기술적 장점뿐 아니라 운영상 결과도 적기
• scale, compliance, cost threshold 같은 재검토 트리거 포함하기

이렇게 하면 문서는 온보딩, 감사, 인수인계에도 훨씬 더 유용해집니다.

재사용하기 좋은 실전 프롬프트 패턴

다음과 같은 프롬프트 틀을 사용해 보세요.

• Decision title
• Status
• Date or ADR number
• Context
• Problem statement
• Constraints
• Alternatives considered
• Decision
• Consequences
• Open questions
• Intended audience
• Required format or headings

이 패턴은 불필요한 추측을 줄이고 추적 가능성을 높여 주기 때문에 architecture-decision-records usage 품질을 안정적으로 끌어올립니다.

설치 전에 이해해야 할 경계

이 스킬은 문서화에 초점을 둡니다. 여러분의 아키텍처 선택이 객관적으로 옳은지 검증해 주는 도구는 아닙니다. 이 스킬은 판단 근거와 tradeoff를 명확히 서술하도록 돕습니다. 팀이 benchmarking, architecture modeling, automated policy check까지 원한다면, 이 스킬은 그런 활동을 대체하는 것이 아니라 그 이후 단계에 두는 편이 맞습니다.

저장소를 읽어보면 내리게 되는 실무적 결론

이 스킬 패키지는 사실상 SKILL.md가 전부이기 때문에 도입은 단순합니다. 먼저 익혀야 할 helper script, reference bundle, rule file이 따로 없습니다. 대신 그만큼 출력 품질은 내장된 자동화보다 사용자의 입력과 리뷰 습관에 더 크게 좌우됩니다.

architecture-decision-records 스킬 FAQ

이미 LLM에 직접 프롬프트할 수 있는데도 architecture-decision-records를 설치할 가치가 있나?

그렇습니다. ADR을 반복적으로 작성하는 팀이라면 특히 그렇습니다. 일반 프롬프트로도 괜찮은 문서 한두 개는 만들 수 있지만, architecture-decision-records skill은 반복적인 의사결정 문서화에 더 적합한 기본 프레임을 제공합니다. 핵심 가치는 일관성과 누락 방지이며, 특히 대안과 결과 섹션에서 그 차이가 크게 납니다.

초보자도 쓰기 쉬운가?

네. 이 스킬은 context, decision, consequences 같은 기본 ADR 개념과, 언제 ADR을 쓰고 언제 생략해도 되는지까지 설명합니다. 그래서 ADR 실무가 익숙하지 않은 팀도 바로 활용할 수 있습니다. 다만 초보자라도 실제 프로젝트 맥락은 직접 제공해야 합니다. 조직의 제약 조건까지 스킬이 스스로 추론해 주지는 않습니다.

architecture-decision-records를 쓰지 않는 편이 나은 경우는 언제인가?

변경이 작고, 일상적이며, 구현 수준에만 머무는 경우에는 굳이 쓰지 않는 편이 낫습니다.

• patch upgrade
• bug fix
• routine maintenance
• 영향도가 낮은 configuration 변경

이런 경우에는 issue comment나 changelog entry 정도로도 충분한 경우가 많습니다.

RFC와는 어떻게 다른가?

RFC는 대개 더 넓은 범위를 다루고, 탐색적이며, 합의가 모이기 전에 작성되는 경우가 많습니다. 반면 ADR은 더 좁고, 결정 자체를 중심에 둡니다. 논의가 어느 정도 성숙한 뒤 “무엇을 왜 결정했는가”를 오래 남는 기록으로 정리해야 한다면 architecture-decision-records가 더 잘 맞습니다.

기존 docs repo에서도 architecture-decision-records를 사용할 수 있나?

네. /docs/adr/, /adr/ 같은 폴더 구조를 가진 저장소와 잘 맞습니다. 이미 ADR-0001 같은 번호 규칙을 쓰고 있다면 프롬프트에 그 형식을 명시하세요. 그래야 생성된 문서가 기존 규약과 자연스럽게 맞아떨어집니다.

이 스킬이 예전 ADR 유지보수에도 도움이 되나?

네. 원본에서 제시하는 proposed, accepted, rejected, deprecated, superseded 같은 라이프사이클 모델은 업데이트 작업에도 유용합니다. 이 스킬은 새 결정을 처음 기록할 때만 쓰는 것이 아니라, 오래된 ADR을 더 명확한 상태 표시와 cross-link를 갖춘 문서로 개정하거나 교체할 때도 도움이 됩니다.

architecture-decision-records 스킬을 더 잘 활용하는 방법

선호하는 답만 주지 말고 decision driver를 제공하기

architecture-decision-records 출력 품질을 가장 빠르게 높이는 방법은, 결정을 밀어붙인 배경 요인을 함께 주는 것입니다.

• scale 요구사항
• latency 요구
• compliance 의무
• 인력 제약
• 비용 한도
• migration 일정

선호 기술만 적어 주면 ADR은 쉽게 사후 정당화 문서처럼 읽히게 됩니다.

실제 대안과 검토 이유를 함께 제공하기

약한 ADR은 대개 대안을 한 줄 언급으로 넘기거나, 실체 없는 strawman option을 만들어냅니다. 더 좋은 프롬프트는 신뢰할 만한 대안을 나열하고, 왜 그 대안들이 실제 검토 대상이었는지도 함께 제공합니다. 그래야 스킬이 뻔한 비교 문장이 아니라 실질적인 tradeoff 섹션을 작성할 수 있습니다.

상태와 재검토 트리거를 명확히 적기

ADR이 다음 중 무엇인지 스킬에 분명하게 알려주세요.

• Proposed
• Accepted
• Rejected
• Deprecated
• Superseded

그리고 어떤 조건에서 재평가할지도 함께 적어 두세요. 이렇게 해야 유지보수 가치가 높아지고, 아직 검토 중인 ADR이 마치 최종 확정된 문서처럼 보이는 문제를 줄일 수 있습니다.

여러 차원의 consequences를 요청하기

더 강한 architecture-decision-records guide 프롬프트는 다음 여러 차원에서 consequences를 적어 달라고 요청합니다.

• engineering complexity
• operations
• security
• cost
• team learning curve
• future flexibility

이렇게 해야 한 줄짜리 “pros and cons”보다 훨씬 의사결정에 도움이 되는 ADR이 나옵니다.

자주 나타나는 실패 패턴을 점검하기

전형적으로 약한 결과물은 다음 특징을 보입니다.

• 어느 프로젝트에나 갖다 붙일 수 있는 일반적인 context
• 기각된 대안이 없음
• 비용 없이 이점만 나열됨
• 실제 구현으로 이어지기엔 너무 넓은 decision statement
• scope나 영향받는 시스템에 대한 표시가 없음

이런 문제가 보인다면, 대개 템플릿 자체보다 입력 정보가 부족한 경우가 많습니다.

넓은 수정 요청보다 구체적인 후속 요청으로 다듬기

첫 초안 이후에는 다음처럼 좁고 구체적인 후속 요청으로 개선하는 편이 효과적입니다.

• Tighten the decision statement to one implementable choice.
• Expand the rejected alternatives with concrete tradeoffs.
• Add operational consequences for deployment and monitoring.
• Rewrite the context so a new team member understands the trigger.
• Mark what assumptions would invalidate this ADR.

막연하게 “더 좋게 만들어 줘”라고 하는 것보다 이런 방식이 훨씬 잘 작동합니다.

팀의 ADR 표준에 맞춰 결과를 조정하기

조직에서 커스텀 템플릿을 쓴다면, 표준 ADR 요소를 팀 heading 구조에 맞게 매핑해 달라고 요청하세요. 예를 들어 다음 항목이 필요할 수 있습니다.

• ownership
• review date
• compliance impact
• rollout plan
• ticket 또는 PRD 링크

결국 architecture-decision-records install 여부는 이런 구조화된 초안 작성 지원이 현재 문서화 프로세스와 잘 맞는지에 따라 판단하는 것이 좋습니다.

링크 규율을 넣어 장기적인 활용 가치를 높이기

좋은 ADR 모음은 찾아보기 쉽습니다. 스킬에 다음 항목을 포함해 달라고 요청하세요.

• 관련 ADR
• superseded-by reference
• 영향받는 시스템
• design doc 또는 incident report 링크

이렇게 해야 문서 한 건으로 끝나는 것이 아니라, 실제로 활용 가능한 의사결정 이력의 일부가 됩니다.

처음 사용한 뒤 architecture-decision-records를 평가하는 가장 좋은 방법

좋은 수용 테스트는 단순합니다. 새로 합류한 엔지니어가 생성된 ADR을 읽고 다음 질문에 답할 수 있는지 보세요.

• 어떤 문제가 있었는가
• 무엇을 결정했는가
• 어떤 대안을 검토했는가
• 왜 이 선택이 채택됐는가
• 팀이 어떤 tradeoff를 받아들였는가
• 언제 이 결정을 다시 검토해야 하는가

이 질문들에 답하기 어렵다면, 프롬프트를 더 구체화하고 더 나은 원본 맥락을 넣어 architecture-decision-records skill을 다시 실행하는 편이 좋습니다.