documentation-and-adrs

documentation-and-adrs 스킬 개요

documentation-and-adrs 스킬이 하는 일

documentation-and-adrs 스킬은 에이전트가 의사결정 중심의 기술 문서를 작성하도록 돕습니다. 특히 Architecture Decision Records(ADR)를 작성할 때 유용합니다. 이 스킬의 진짜 역할은 “문서를 더 많이 쓰는 것”이 아니라, “팀이 왜 이 방식을 선택했는지, 어떤 제약이 중요했는지, 어떤 대안이 배제되었는지 기록하는 것”입니다. 그래서 코드만으로는 앞으로의 유지보수 판단을 설명하기 어려울 때 특히 효과적입니다.

가장 잘 맞는 사용자와 작업

이 스킬은 엔지니어, 테크 리드, 아키텍트, 그리고 아키텍처·API·인프라·인증·데이터 모델·사용자 노출 기능 변경과 관련된 Technical Writing을 하는 팀에 가장 적합합니다. documentation-and-adrs는 단순히 오늘의 작업을 깔끔하게 설명하는 문서가 아니라, 미래의 엔지니어나 에이전트를 위한 지속 가능한 맥락이 필요할 때 사용하세요.

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

일반 프롬프트는 깔끔한 요약을 만들어낼 수 있지만, documentation-and-adrs skill은 결정 기록에 맞춰져 있습니다. 즉, 맥락, 제약, 선택지, 트레이드오프, 그리고 결과를 다룹니다. 이 프레이밍이 중요한 이유는, 문서가 부족한 경우 대부분 구현은 설명하면서도 미래의 유지보수자가 실제로 필요한 판단 근거는 빠뜨리기 때문입니다.

설치하지 않는 것이 나은 경우

인라인 코드 주석만 필요하거나, 가벼운 README 정리만 원하거나, 버릴 프로토타입용 문서를 만들고 싶다면 이 스킬은 건너뛰세요. 또한 구현 자체가 의도를 충분히 드러내고, 보존할 만한 의사결정 이력이 없는 자명한 코드 경로에도 잘 맞지 않습니다.

documentation-and-adrs 스킬 사용법

설치 맥락과 읽기 시작할 위치

documentation-and-adrs install을 하려면 addyosmani/agent-skills 저장소에서 스킬을 추가한 뒤, 먼저 skills/documentation-and-adrs/SKILL.md를 읽으세요. 이 스킬은 단일 안내 파일로 제공되므로, 참조 스크립트나 보조 파일에 기대기 어렵습니다. 즉, 도구 기반 스킬보다 입력 품질의 영향이 훨씬 큽니다.

환경이 스킬 설치를 지원한다면 다음을 사용하세요:
npx skills add addyosmani/agent-skills --skill documentation-and-adrs

그다음 확인할 파일:

• skills/documentation-and-adrs/SKILL.md

documentation-and-adrs 스킬에 필요한 입력

이 스킬은 원하는 출력 형식만 던져주는 것보다, 결정의 맥락을 제공할 때 가장 잘 작동합니다. 좋은 입력에는 보통 다음이 포함됩니다:

• 제안하려는 변경 내용
• 영향을 받는 시스템이나 API
• 성능, 규정 준수, 비용, 마감, 호환성 같은 제약
• 검토한 대안들
• 예상되는 결과와 위험
• 대상 독자와 출력 위치, 예: docs/adr/ 또는 docs/architecture/

약한 입력: “GraphQL로 전환하는 ADR을 작성해 줘.”

더 강한 입력:

• 현재 상태: 모바일 클라이언트 전반에서 버전 관리에 어려움이 있는 REST API
• 필요한 결정: 새 제품 영역에 GraphQL을 도입할지 여부
• 제약: 기존 REST 엔드포인트는 12개월간 유지, 플랫폼 팀 규모가 작음, 필드 수준의 클라이언트 유연성이 필요함
• 대안: REST 규칙 개선, tRPC, GraphQL gateway
• 결정 책임자: 플랫폼 리드
• 출력: status, context, decision, consequences, rejected alternatives를 포함한 ADR

더 나은 documentation-and-adrs 활용을 위한 프롬프트 작성법

좋은 documentation-and-adrs usage 프롬프트는 구조와 판단 근거의 질을 함께 요구해야 합니다. 다음 순서가 안정적입니다:

1. 결정 종류나 문서 유형을 명시한다.
2. 프로젝트 맥락과 제약을 제공한다.
3. 검토한 옵션을 적는다.
4. 트레이드오프, 가정, 후속 조치를 드러내도록 요청한다.
5. 대상 형식을 지정한다.

예시 프롬프트:
“documentation-and-adrs 스킬을 사용해서 우리 B2B SaaS의 인증 전략 선택 ADR을 작성해 주세요. hosted auth, self-managed OAuth, passkeys-first를 비교해 주세요. context, constraints, decision drivers, rejected options, consequences, migration notes, open questions를 포함해 주세요. 독자는 앞으로 이 시스템을 다룰 백엔드 및 보안 엔지니어입니다.”

실제 팀을 위한 권장 워크플로

실무에서 documentation-and-adrs guide 워크플로를 쓸 때는 다음 순서가 좋습니다:

1. 이슈, PR, 아키텍처 노트, 팀 채팅에서 사실을 모은다.
2. 초안을 쓰기 전에 에이전트에게 결정 요인을 먼저 추출하게 한다.
3. 1차 초안에서 빠진 대안과 명시되지 않은 제약을 검토한다.
4. 결과물을 안정적인 이름과 위치를 가진 저장소 문서나 ADR로 옮긴다.
5. 실제 운영에서 결정이 검증되면 기록을 업데이트한다.

이 스킬은 구체적인 원본 자료와 함께 쓸 때 Technical Writing에 특히 강합니다. 반대로, 어디에도 제공되지 않은 비즈니스적 또는 아키텍처적 판단 근거를 에이전트가 추론하게 만들면 훨씬 약해집니다.

documentation-and-adrs 스킬 FAQ

documentation-and-adrs는 Technical Writing 입문자에게도 적합한가요?

네, 다만 입문자도 그 결정의 사실관계에 접근할 수 있어야 합니다. 이 스킬은 ADR과 의사결정 문서에 유용한 구조를 제공하지만, 기술적 판단 자체를 대신해 주지는 않습니다. 입문자는 문서를 백지에서 만들라고 하기보다, 회의 메모, 이슈 링크, 간단한 장단점 목록을 제공할 때 더 좋은 결과를 얻는 경우가 많습니다.

“문서 작성해 줘”라고 요청하는 것과 어떻게 다른가요?

일반적인 문서 프롬프트는 보통 가독성에 최적화됩니다. 반면 documentation-and-adrs는 결정의 유지보수성에 최적화되어 있습니다. 왜 이 경로가 선택되었는지, 어떤 제약이 있었는지, 앞으로 문서를 읽는 사람이 무엇을 알아야 변경할 수 있는지를 중심에 둡니다. 이 차이는 아키텍처, 공개 API, 인프라 선택에서 특히 중요합니다.

이 스킬의 범위는 어디까지인가요?

이 스킬은 저장소 전체 문서 시스템이나 스타일 린터, 자동화된 문서 생성기가 아닙니다. 프로세스와 구조에 대한 가이드를 제공할 뿐, 도구로 강제되는 스크립트나 템플릿을 제공하지는 않습니다. 문서 동기화 자동화, 규칙 강제, 퍼블리싱 워크플로가 필요하다면 별도 도구를 함께 써야 합니다.

언제 documentation-and-adrs 스킬을 쓰지 말아야 하나요?

사소한 구현 디테일, 자명한 리팩터링, 중복된 코드 주석, 장기 가치가 없는 실험적 프로토타입에는 사용하지 마세요. 팀이 아직 실제 결정을 내리지 않았다면, 이 스킬로 옵션 비교는 할 수 있지만, 결정이 끝나기 전에 최종 ADR이 이미 존재하는 것처럼 꾸미면 안 됩니다.

documentation-and-adrs 스킬 개선 방법

요약용 입력이 아니라 결정용 입력을 제공하세요

documentation-and-adrs skill 결과를 가장 빠르게 개선하는 방법은 의사결정을 뒷받침하는 증거를 주는 것입니다. 배제한 대안, 제약, 예상 결과를 함께 넣으세요. 이런 정보가 없으면 결과는 깔끔해 보여도 일반론처럼 느껴집니다. 가능하다면 설계 문서, PR 설명, RFC, 인시던트 리뷰의 일부를 제공하세요.

흔한 실패 패턴을 점검하세요

가장 흔한 문제는 다음과 같습니다:

• 이유를 기록해야 하는데 구현 세부사항만 반복함
• 대안만 나열하고 왜 탈락했는지 설명하지 않음
• 위험, 마이그레이션 비용, 운영상 결과를 빼먹음
• 미래 유지보수자가 아니라 오늘의 리뷰어만을 위한 문서를 씀

이런 문제가 보이면 “decision drivers, rejected alternatives, downstream consequences”에 초점을 맞춰 수정해 달라고 요청하세요.

첫 초안 이후에는 구조를 다듬으세요

첫 번째 버전 이후에는 전부 다시 쓰기보다 약한 부분을 더 단단하게 만들도록 요청하는 편이 좋습니다. 유용한 후속 요청 예시는 다음과 같습니다:

• “트레이드오프를 더 명확하게 해 주세요.”
• “가정과 이 결정을 바꿀 조건을 추가해 주세요.”
• “즉시 발생하는 결과와 장기 유지보수 영향을 분리해 주세요.”
• “이 하위 시스템을 모르는 미래 엔지니어를 위해 다시 써 주세요.”

저장소 관례에 맞게 스킬을 조정하세요

documentation-and-adrs for Technical Writing을 더 유용하게 만들려면, 파일명 규칙, ADR 형식, 문서 위치를 에이전트에게 알려 주세요. 예를 들어 docs/adrs/0007-auth-strategy.md처럼 순번형 ADR을 쓰는지, 아니면 docs/architecture/ 아래의 주제별 문서를 쓰는지 지정할 수 있습니다. 프롬프트가 저장소의 문서 관례에 더 가까울수록 생성 후 손볼 일이 줄어듭니다.