adr-skill

adr-skill 스킬 개요

adr-skill이 하는 일

adr-skill은 Architecture Decision Record를 단순한 이력 메모가 아니라, 바로 구현에 옮길 수 있는 문서로 만들고 유지하도록 돕습니다. 이 스킬의 핵심 가치는 아키텍처 선택을, 코딩 에이전트가 추가 설명 없이도 실행에 옮길 수 있는 ADR로 바꿔준다는 점에 있습니다. 예를 들어 명확한 제약 조건, 분명한 비목표, 변경할 파일 경로, 검증 단계, 구체적인 결과와 영향까지 문서에 담도록 밀어줍니다.

adr-skill이 가장 잘 맞는 대상

이 스킬은 이후 실제 코딩 작업의 기준이 될 의사결정을 문서화하는 엔지니어링 리드, 스태프 엔지니어, 플랫폼 팀, 테크니컬 라이터에게 특히 잘 맞습니다. 되돌리기 어려운 결정이거나, 여러 기여자에게 영향을 주거나, 사람과 AI 에이전트 모두가 이해해야 하는 경우 특히 유용합니다.

adr-skill의 핵심 해결 과제

다음과 같은 상황이라면 adr-skill을 쓰는 것이 적합합니다.

• 새로운 아키텍처 결정을 제안해야 할 때
• 구현에 들어가기 전에 결정을 문서화해야 할 때
• 기존 ADR을 수정하거나 대체해야 할 때
• 아직 ADR이 없는 저장소에 처음 체계를 잡아야 할 때
• 코드베이스 전반에 일관된 ADR 구조를 강제하고 싶을 때

특히 adr-skill for Technical Writing 관점에서 보면, 이해관계자가 읽기 쉬우면서도 구현 담당자가 바로 실행할 수 있을 정도로 구체적인 의사결정 문서를 만드는 데 가장 잘 맞습니다.

adr-skill이 돋보이는 이유

adr-skill의 가장 큰 차별점은 에이전트 우선(agent-first) 관점입니다. 이 스킬은 배경, 결정, 결과 정도에서 멈추지 않습니다. 영향을 받는 경로, 의존성, 따라야 할 패턴, 피해야 할 패턴, 설정 변경, 검증 기준까지 포함한 구현 계획을 요구합니다. 그래서 일반적인 “ADR 하나 써줘” 프롬프트보다 훨씬 실행 가능성이 높습니다.

도입 전에 확인할 점

adr-skill을 설치하거나 본격적으로 의존하기 전에, 팀이 정말로 ADR을 실행의 기준 문서로 쓸 생각이 있는지 먼저 확인해야 합니다. 단순한 배경 설명 메모 정도만 필요하다면 이 스킬의 구조가 과하다고 느껴질 수 있습니다. 반대로, 핸드오프 이후에도 살아남고 모호함을 줄여주는 ADR이 필요하다면, 바로 그 추가적인 엄밀함이 이 스킬의 목적입니다.

adr-skill 스킬 사용 방법

adr-skill 설치 맥락

저장소 발췌본에는 SKILL.md 안에 스킬 전용 설치 명령이 직접 드러나 있지 않지만, 일반적으로는 다음 패턴을 사용합니다.

npx skills add vercel/ai --skill adr-skill

추가한 뒤에는 아키텍처 결정을 내리거나 문서화하려는 시점에 AI 코딩 환경에서 adr-skill을 사용하면 됩니다.

먼저 읽어야 할 파일

adr-skill usage를 가장 빠르게 제대로 익히고 싶다면, 다음 순서로 읽는 것이 좋습니다.

1. SKILL.md
2. references/adr-conventions.md
3. references/review-checklist.md
4. references/template-variants.md
5. references/examples.md

그다음에는 아래 스크립트도 확인하세요.

• scripts/bootstrap_adr.js
• scripts/new_adr.js
• scripts/set_adr_status.js

이 순서가 중요한 이유는 분명합니다. conventions 문서는 ADR을 어디에 둘지 알려주고, checklist는 품질 기준을 설명하며, template variants는 어떤 구조를 선택해야 할지 돕고, examples는 어느 정도까지 구체적으로 써야 하는지 감을 잡게 해줍니다.

adr-skill이 사용자에게 필요로 하는 입력

adr-skill은 다음 정보를 줄수록 가장 좋은 결과를 냅니다.

• 내려야 할 결정
• 왜 지금 이 결정을 해야 하는지 보여주는 촉발 요인 또는 문제
• 저장소 맥락과 기존 아키텍처
• 지연 시간, 비용, 컴플라이언스, 배포 모델, 팀 역량 한계 같은 제약 조건
• 비목표
• 영향을 받을 것으로 예상되는 파일, 모듈, 서비스, 워크플로
• 이미 검토한 대안

이 정보 없이도 초안은 만들 수 있지만, 그런 경우 adr-skill은 실행 가능한 ADR보다는 일반론적인 ADR을 내놓기 쉽습니다.

거친 아이디어를 강한 프롬프트로 바꾸는 법

약한 프롬프트 예시:

• “Write an ADR for switching databases.”

adr-skill usage에 더 적합한 강한 프롬프트 예시:

• “Create an ADR proposing SQLite for local dev and CI while keeping PostgreSQL in production. Context: shared Postgres makes tests flaky and adds 3+ minutes to CI setup. Constraints: local setup must work offline, CI setup under 10 seconds, production schema remains Postgres-compatible. Non-goals: no production migration, no full ORM rewrite. Affected paths likely include src/db/, test setup, and CI config. Include implementation plan and verification steps.”

두 번째 프롬프트는 다른 엔지니어나 에이전트가 실제로 구현할 수 있을 정도의 의사결정 문서를 쓰기에 충분한 재료를 제공합니다.

목적에 맞게 템플릿을 고르기

결정이 거의 굳어져 있고, 왜 그렇게 했는지·무엇이 바뀌는지·어떻게 구현하는지만 정리하면 되는 상황이라면 simple template이 적합합니다.

반대로 실제로 경쟁하는 선택지가 있고, 여러 결정 요인이 얽혀 있거나, 이해관계자가 트레이드오프를 검토해야 한다면 MADR 스타일 템플릿이 더 잘 맞습니다. 이 스킬은 두 패턴을 모두 제공합니다.

• assets/templates/adr-simple.md
• assets/templates/adr-madr.md

실무에서의 일반적인 adr-skill 워크플로

실제로는 보통 이런 흐름으로 씁니다.

1. 이 변경이 ADR로 남길 가치가 있는지 스킬에 먼저 물어본다.
2. 스킬이 맥락, 제약, 비목표를 질문하게 둔다.
3. 적절한 템플릿으로 ADR 초안을 만든다.
4. references/review-checklist.md로 초안을 검증한다.
5. 저장소 고유의 경로, 네이밍, 관례에 맞게 수정한다.
6. 선택한 ADR 디렉터리에 파일을 생성하거나 갱신한다.
7. 필요하면 나중에 라이프사이클 상태를 변경한다.

바로 이 지점에서 adr-skill guide의 가치가 드러납니다. 첫 초안을 써주는 데서 끝나는 것이 아니라, ADR의 전체 수명주기를 지원합니다.

ADR이 없는 저장소에서 adr-skill로 처음 체계 잡기

저장소에 아직 ADR 구조가 없다면 포함된 아래 스크립트가 유용합니다.

• scripts/bootstrap_adr.js

이 스크립트는 ADR 디렉터리를 만들고, index/README를 생성하고, 초기 문서인 “Adopt architecture decision records”까지 추가할 수 있습니다. 폴더 구조를 손으로 임의 설계하는 것보다 나은 이유는, 이 저장소 안에 이미 디렉터리 감지 방식이나 네이밍 전략 같은 관례 선택이 반영되어 있기 때문입니다.

새 ADR을 더 빠르게 만드는 방법

반복 가능한 방식으로 ADR을 만들고 싶다면 scripts/new_adr.js를 살펴보세요. 다음과 같은 실무적인 옵션을 지원합니다.

• repo root
• ADR directory override
• title
• status
• template choice: simple or madr
• filename strategy
• deciders, consulted, and informed fields
• index updates

이런 점 때문에 일회성 문서 생성이 아니라 반복 가능한 작업 방식을 원하는 팀에게는 adr-skill install의 가치가 더 커집니다.

상태 변경은 어떻게 처리되는가

함께 제공되는 scripts/set_adr_status.js는 ADR 상태를 해당 문서 안에서 직접 업데이트합니다. 팀이 ADR을 단순한 정적 markdown 파일이 아니라 proposed, accepted, rejected, deprecated, superseded 같은 상태를 가진 살아 있는 문서로 다룬다면 이 점이 중요합니다.

결과물 품질에 영향을 주는 저장소 관례

adr-skill은 ADR 품질에 대해 분명한 기준을 갖고 있습니다.

• 제약 조건은 측정 가능해야 한다
• 비목표는 명시적이어야 한다
• consequences는 후속 작업으로 이어져야 한다
• 구현 계획에는 실제 경로가 들어가야 한다
• verification은 결정이 올바르게 구현되었는지 확인하는 방법을 보여줘야 한다

프롬프트에서 이런 요소를 빠뜨리면, 문장 자체가 매끈해 보여도 결과물 품질은 크게 떨어집니다.

맞춰야 할 디렉터리 및 네이밍 관례

references/adr-conventions.md에 따르면, adr-skill은 먼저 기존 저장소 관례를 우선하고, 별도 관례가 없다면 docs/decisions/나 adr/ 같은 위치를 제안합니다. 파일 이름도 저장소에 이미 다른 규칙이 없는 한 YYYY-MM-DD-title-with-dashes.md처럼 예측 가능한 형식을 선호합니다.

즉, 프로젝트에 이미 정착된 패턴이 있다면 adr-skill의 기본값을 무조건 밀어붙이면 안 됩니다.

adr-skill 스킬 FAQ

adr-skill은 일반 프롬프트보다 더 나은가?

목표가 오래 살아남는, 구현 지향적인 ADR이라면 그렇습니다. 일반 프롬프트도 읽기 좋은 문서는 만들 수 있지만, adr-skill은 촉발 요인, 측정 가능한 제약, 비목표, 구현 계획, 검토 기준까지 구조화해 줍니다. 보통은 이런 점이 즉흥적인 프롬프트보다 모호함을 더 많이 줄여줍니다.

adr-skill은 초보자에게도 적합한가?

네, 다만 한 가지 전제는 있습니다. adr-skill은 초보자가 더 나은 ADR을 쓰도록 도와주지만, 없는 아키텍처 맥락을 대신 만들어내지는 못합니다. ADR 자체가 낯설다면 examples와 template variants가 학습 곡선을 낮춰줍니다. 하지만 문서화 대상 시스템 자체가 낯설다면, 먼저 더 많은 맥락을 수집해야 할 가능성이 큽니다.

adr-skill이 잘 맞지 않는 경우는 언제인가?

다음 상황이라면 adr-skill을 굳이 쓰지 않는 편이 낫습니다.

• 변경이 사소하고 되돌리기 쉽다
• 짧은 설계 메모만 있으면 된다
• 팀이 ADR을 장기적으로 유지하지 않는다
• 구현을 이끌 문서로 아무도 활용하지 않는다

이런 경우에는 스킬의 구조가 결정의 무게에 비해 지나치게 무겁게 느껴질 수 있습니다.

adr-skill은 수정된 ADR이나 대체된 ADR도 처리할 수 있나?

네. 이 스킬은 새 ADR 작성에만 한정되지 않습니다. 기존 결정을 업데이트하고, accepted, rejected, deprecated, superseded 상태로 관리하는 흐름도 지원합니다. 아키텍처가 고정돼 있지 않고 계속 진화하는 저장소라면 이 기능이 중요합니다.

adr-skill은 엔지니어만 위한 도구인가, 아니면 테크니컬 라이터에게도 도움이 되나?

둘 다에게 도움이 됩니다. Technical Writing 관점에서 adr-skill이 유용한 이유는, 의사결정 문서가 무엇이 바뀌는지, 왜 지금 필요한지, 어디까지가 범위 밖인지, 구현은 어떻게 검증해야 하는지를 반드시 답하게 만들기 때문입니다. 그래서 엔지니어링 팀과 미래의 유지보수 담당자 모두에게 더 실용적인 문서가 됩니다.

포함된 스크립트를 꼭 써야 하나?

아니요. adr-skill을 순수하게 초안 작성 및 리뷰 보조 도구로만 써도 됩니다. 스크립트는 저장소 전반에서 생성 방식 표준화, 초기 구조 설정, 상태 업데이트까지 관리하고 싶을 때 의미가 커집니다.

adr-skill 스킬을 더 잘 활용하는 방법

주제만이 아니라 의사결정의 촉발 요인을 adr-skill에 주기

adr-skill 결과를 개선하는 가장 좋은 방법은, 왜 이 ADR이 지금 필요한지 설명하는 것입니다. “캐싱 관련 ADR이 필요함”은 약합니다. 반면 “현재 API p95가 900ms이고, 트래픽은 두 배로 늘었으며, 상품 검색에 200ms 이하 읽기 응답이 필요하다”는 훨씬 강합니다. 이 촉발 요인이 문서 전체의 방향을 결정합니다.

구체적인 제약 조건과 수치를 명시하기

adr-skill은 측정 가능한 결정을 다루도록 설계되어 있습니다. 가능하면 숫자와 한계를 넣으세요.

• latency targets
• cost ceilings
• compatibility requirements
• rollout windows
• compliance constraints
• operational ownership boundaries

이렇게 해야 결과물이 추상적인 아키텍처 설명을 넘어, 실제 의사결정에 쓸 수 있는 문서로 올라갑니다.

비목표를 초반부터 포함하기

많은 ADR이 실패하는 이유는 너무 많은 것을 암묵적으로 포함해 버리기 때문입니다. 무엇이 명확히 범위 밖인지 adr-skill에 알려주세요.

• no migration of production data
• no API version change
• no vendor lock-in decision in this ADR
• no UI redesign

비목표가 분명할수록 범위 확장을 막을 수 있고, 구현 계획도 더 좋아집니다.

실제 경로와 패턴을 짚어주기

실제로 쓸 수 있는 구현 계획이 필요하다면, 저장소 안의 실제 파일, 모듈, 또는 이미 존재하는 유사 코드 패턴을 함께 알려주세요. 예를 들면 다음과 같습니다.

• “Follow the pattern in src/payments/stripe.ts.”
• “Avoid adding logic to pages/api/*; use route handlers under app/api/.”
• “Config lives in infra/terraform/ and .github/workflows/.”

이것이야말로 adr-skill skill 출력 품질을 가장 크게 끌어올리는 레버 중 하나입니다.

첫 초안 뒤에는 review checklist로 다시 점검하기

첫 출력에서 멈추지 마세요. ADR을 references/review-checklist.md와 대조해 보되, 특히 아래를 확인하는 것이 좋습니다.

• 새로 합류한 사람도 촉발 요인을 이해할 수 있는가?
• 제약 조건이 실제 행동으로 옮길 만큼 구체적인가?
• 영향을 받는 경로가 명시되어 있는가?
• 후속 작업과 검증 단계가 분명한가?
• consequences가 단지 결정을 모호하게 반복하는 수준에 그치지 않는가?

이 checklist에 adr-skill의 실질적인 가치가 많이 담겨 있습니다.

결정 형태에 맞는 템플릿 선택하기

자주 생기는 실패 패턴 중 하나는 단순한 선택에 옵션이 많은 MADR 구조를 쓰거나, 반대로 이해관계자에게 트레이드오프 기록이 필요한데 simple template를 쓰는 경우입니다. 결정의 복잡도에 맞춰 템플릿을 골라야 ADR이 읽기 좋게 유지됩니다.

자리 채우기식 문장을 그대로 두지 않기

저장소의 examples는 placeholder 수준의 문구가 실제 ADR에 남아 있으면 안 된다는 점을 분명히 보여줍니다. 첫 초안에 “use best practices”나 “update relevant files” 같은 모호한 표현이 있다면, 아래처럼 운영 가능한 세부 정보로 다시 써야 합니다.

• specific dependency versions
• named configs
• migration order
• rollout or rollback checks
• exact test classes or suites

결정 자체보다 consequences도 함께 다듬기

많은 사용자가 Decision 섹션은 열심히 다듬으면서 Consequences는 소홀히 합니다. 이는 실수입니다. 강한 consequences는 앞으로 구현 담당자가 무엇을 더 쉽게 하게 되는지, 무엇이 더 어려워지는지, 어떤 위험이나 비용이 생기는지, 다음에 무엇이 필수가 되는지를 알려줘야 합니다. consequences가 약하면 ADR은 실행을 제대로 이끌지 못합니다.

팀 차원의 도입을 위해 adr-skill을 다듬는 법

팀 전체에서 더 폭넓게 쓰고 싶다면, adr-skill 주변에서 최소한 세 가지를 표준화하는 것이 좋습니다.

• 하나의 ADR directory convention
• 결정 유형별 하나의 기본 template choice
• 하나의 status vocabulary

이렇게 해야 마찰이 줄고, 여러 저장소에서 스크립트 활용도도 높아집니다.

배포 전에 하는 최고의 최종 점검

adr-skill로 작성한 ADR을 수용하기 전에, 마지막으로 한 가지 어려운 질문을 던져보세요. 숨은 구전 지식 없이도 코딩 에이전트가 이 변경을 구현할 수 있는가? 대답이 아니오라면, 예가 될 때까지 맥락, 경로, 패턴, 제약, 검증 단계를 더 보강해야 합니다.