clanker25/ai

ADR 기술

철학

이 기술로 생성된 ADR은 코딩 에이전트를 위한 실행 가능한 명세서입니다. 인간이 결정을 승인하고, 에이전트가 이를 구현합니다. ADR에는 에이전트가 추가 질문 없이 올바른 코드를 작성하는 데 필요한 모든 것이 포함되어야 합니다.

다음을 의미합니다:

• 제약 조건은 명시적이고 측정 가능해야 하며, 모호한 느낌이 아닌 구체적이어야 합니다.
• 결정은 실행 가능할 정도로 구체적이어야 합니다("데이터베이스 사용"이 아닌 "pgvector와 함께 PostgreSQL 16 사용").
• 결과는 구체적인 후속 작업으로 매핑되어야 합니다.
• 범위 확장을 방지하기 위해 비목표를 명시해야 합니다.
• ADR은 자체 완결적이어야 하며, 암묵적 지식을 가정하지 않아야 합니다.
• ADR에는 구현 계획이 포함되어야 합니다 — 어떤 파일을 수정할지, 어떤 패턴을 따를지, 어떤 테스트를 작성할지, 결정이 올바르게 구현되었는지 확인하는 방법.

ADR을 작성해야 하는 경우

다음과 같은 결정을 내릴 때 ADR을 작성하세요:

• 시스템 구축 또는 운영 방식을 변경하는 경우(새 종속성, 아키텍처 패턴, 인프라 선택, API 설계)
• 코드가 작성된 후 되돌리기 어려운 경우
• 이 코드베이스에서 나중에 작업할 다른 사람이나 에이전트에게 영향을 미치는 경우
• 고려되고 기각된 실제 대안이 있는 경우

다음의 경우 ADR을 작성하지 마세요:

• 기존 패턴 내에서의 일상적인 구현 선택
• 버그 수정 또는 오타 수정
• 기존 ADR에 이미 캡처된 결정(대신 업데이트)
• 린터나 포매터에서 이미 다루는 스타일 선호도

의문이 들 때: 이 코드베이스에서 작업하는 미래의 에이전트가 이 결정이 왜 내려졌는지 알면 도움이 될 경우 ADR을 작성하세요.

사전 ADR 트리거(에이전트용)

리포지토리에서 코딩하는 에이전트라면 다음 상황 중 하나를 만나면 멈추고 ADR을 제안한 후 계속하세요:

• 프로젝트에 아직 존재하지 않는 새 종속성을 도입하려는 경우
• 다른 코드가 따라야 할 새로운 아키텍처 패턴(새로운 오류 처리 방식, 새 데이터 액세스 계층, 새 API 규칙)을 만들려는 경우
• 두 가지 이상의 실제 대안 사이에서 선택해야 하고, 그 트레이드오프가 자명하지 않은 경우
• 기존에 승인된 ADR과 모순되는 것을 변경하려는 경우
• "왜"를 설명하는 긴 코드 주석을 작성하고 있다는 것을 깨달은 경우 — 그 근거는 ADR에 속합니다.

제안 방법: 인간에게 어떤 결정에 직면했는지, 왜 중요한지 알리고 ADR로 캡처할지 물어보세요. 그렇다면 전체 4단계 워크플로를 실행하세요. 아니라면 결정을 코드 주석에 기록하고 계속 진행하세요.

ADR 생성: 4단계 워크플로

모든 ADR은 네 단계를 거칩니다. 단계를 건너뛰지 마세요.

1단계: 코드베이스 스캔

질문을 하기 전에 리포지토리에서 컨텍스트를 수집하세요:

1. 기존 ADR 찾기. contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/에서 기존 기록을 확인하세요. 읽어보세요. 다음 사항을 기록하세요:

   • 기존 규칙(디렉터리, 이름 지정, 템플릿 스타일)
   • 현재 결정과 관련되거나 제약하는 결정
   • 이 새 결정이 대체할 수 있는 모든 ADR

2. 기술 스택 확인. package.json, go.mod, requirements.txt, Cargo.toml 또는 동등한 파일을 읽으세요. 관련 종속성 및 버전을 기록하세요.

3. 관련 코드 패턴 찾기. 결정이 특정 영역(예: "인증 처리 방법")과 관련된 경우 기존 구현을 스캔하세요. 결정의 영향을 받을 특정 파일, 디렉터리 및 패턴을 식별하세요.

4. 코드에서 ADR 참조 확인. 주석과 문서에서 ADR 참조를 찾으세요(아래 "코드 ↔ ADR 연결" 참조). 이를 통해 기존 결정이 코드베이스의 어느 부분을 규율하는지 알 수 있습니다.

5. 발견한 내용을 기록하세요. 이 컨텍스트를 2단계로 가져가세요. 질문을 더 날카롭게 하고 ADR이 기존 결정과 모순되는 것을 방지합니다.

2단계: 의도 파악(소크라틱)

인간과 인터뷰하여 결정 공간을 이해하세요. 한 번에 하나씩 질문하고 이전 답변을 기반으로 하세요. 질문 목록을 한꺼번에 던지지 마세요.

핵심 질문(대략 이 순서대로 물어보고, 컨텍스트나 1단계에서 이미 명확한 것은 건너뛰세요):

1. 무엇을 결정하고 있나요? — 간결하고 구체적인 제목을 얻으세요. 동사구를 유도하세요("X 선택", "Y 채택", "Z를 W로 대체").
2. 왜 지금인가요? — 무엇이 고장 났는지, 무엇이 변경되고 있는지, 또는 아무것도 하지 않으면 무엇이 고장 날지? 이것이 트리거입니다.
3. 어떤 제약 조건이 있나요? — 기술 스택, 일정, 예산, 팀 규모, 기존 코드, 규정 준수. 구체적으로 말하세요. 1단계에서 찾은 내용을 참조하세요("이미 X를 사용하고 있는 것을 확인했습니다. 이것이 이 결정을 제약합니까?").
4. 성공은 어떻게 생겼나요? — 측정 가능한 결과. "작동한다"는 말을 넘어 구체적인 내용(지연 시간, 처리량, 개발자 경험, 유지보수 부담)으로 유도하세요.
5. 어떤 옵션을 고려했나요? — 최소 두 가지. 각각의 핵심 트레이드오프는 무엇인가요? 옵션이 하나만 있다면 대안이 기각된 이유를 설명하도록 도와주세요.
6. 현재 선호하는 것은 무엇인가요? — 직관을 초기에 캡처하세요. 종종 명시되지 않은 우선순위를 드러냅니다.
7. 누가 알거나 승인해야 하나요? — 결정권자, 자문을 구한 전문가, 정보를 받아야 하는 이해관계자.
8. 에이전트가 이를 구현하려면 무엇이 필요할까요? — 영향을 받는 파일/디렉터리는 무엇인가요? 따라야 할 기존 패턴은 무엇인가요? 피해야 할 것은 무엇인가요? 작동을 증명할 테스트는 무엇인가요? 이것은 구현 계획에 직접적으로 반영됩니다.

적응형 후속 질문: 답변에 기반하여 결정이 모호한 부분을 더 깊이 파고드세요. 일반적인 후속 질문:

• "이 결정이 잘못되었을 때 최악의 결과는 무엇인가요?"
• "6개월 후에 이를 재검토하게 만드는 것은 무엇인가요?"
• "명시적으로 하지 않기로 선택한 것이 있나요?"
• "코드베이스의 기존 선례나 패턴과 관련이 있나요?"
• "[기존 ADR/패턴]을 찾았습니다. 이 새 결정이 그것과 상호 작용합니까?"

언제 멈출까요: 구현 계획을 포함한 ADR의 모든 섹션을 추측 없이 채울 수 있을 때입니다. 어떤 섹션이라도 추측하고 있다면 다른 질문을 하세요.

의도 요약 게이트: 3단계로 이동하기 전에 캡처한 내용의 구조화된 요약을 제시하고 인간에게 확인 또는 수정을 요청하세요:

ADR에 대해 캡처한 내용은 다음과 같습니다:

• 제목: {제목}
• 트리거: {왜 지금}
• 제약 조건: {목록}
• 옵션: {옵션 1} vs {옵션 2} [vs ...]
• 선호: {어떤 옵션과 이유}
• 비목표: {명시적으로 범위 밖인 것}
• 관련 ADR/코드: {이것과 상호 작용하는 기존 것}
• 영향을 받는 파일/영역: {코드베이스에서 이것이 적용되는 곳}
• 검증: {올바르게 구현되었는지 확인하는 방법}

이것이 당신의 의도를 캡처했나요? 추가하거나 수정할 사항이 있나요?

인간이 요약을 확인할 때까지 3단계로 진행하지 마세요.

3단계: ADR 초안 작성

1. ADR 디렉터리를 선택하세요.

   • 하나가 존재하면(1단계에서 찾음) 사용하세요.
   • 없으면 contributing/decisions/(contributing/이 있는 경우), docs/decisions/(MADR 기본값), 또는 adr/(더 간단한 리포지토리)를 만드세요.

2. 파일명 전략을 선택하세요.

   • 기존 ADR이 날짜 접두사(YYYY-MM-DD-...)를 사용하면 계속 사용하세요.
   • 그렇지 않으면 슬러그 전용 파일명(choose-database.md)을 사용하세요.

3. 템플릿을 선택하세요.

   • 간단한 결정(하나의 명확한 승자, 최소 트레이드오프)에는 assets/templates/adr-simple.md를 사용하세요.
   • 여러 옵션을 구조화된 장단점/동기와 함께 문서화해야 할 때는 assets/templates/adr-madr.md를 사용하세요.
   • 참고: references/template-variants.md.

4. 확인된 의도 요약에서 모든 섹션을 채우세요. 플레이스홀더 텍스트를 남기지 마세요. 모든 섹션에는 실제 내용이 있거나 제거되어야 합니다(선택적 섹션만 해당).

5. 구현 계획을 작성하세요. 이것은 에이전트 우선 ADR에서 가장 중요한 섹션입니다. 다음 에이전트에게 정확히 무엇을 해야 하는지 알려줍니다. 템플릿의 구조를 참조하세요.

6. 검증 기준을 체크박스로 작성하세요. 에이전트가 프로그래밍 방식으로 또는 수동으로 각각을 확인할 수 있을 만큼 구체적이어야 합니다.

7. 파일을 생성하세요.

   • 권장: scripts/new_adr.js 실행(디렉터리, 이름 지정 및 선택적 인덱스 업데이트 처리).
   • 스크립트를 실행할 수 없으면 assets/templates/에서 템플릿을 복사하여 수동으로 채우세요.

4단계: 체크리스트 검토

초안 작성 후 references/review-checklist.md의 에이전트 준비 상태 체크리스트에 대해 ADR을 검토하세요.

검토를 요약으로 제시하고 원시 체크리스트 덤프가 아닌 형식으로 제시하세요. 형식:

ADR 검토

✅ 통과: {견고한 항목 목록 — 예: "컨텍스트가 자체 완결적이고, 구현 계획이 영향을 받는 파일을 다루며, 검증 기준이 확인 가능함"}

⚠️ 발견된 격차:

• {특정 격차 1 — 예: "구현 계획이 테스트 파일을 언급하지 않음 — 어떤 테스트 스위트가 이를 다루어야 할까요?"}
• {특정 격차 2}

권장 사항: {제출 / 먼저 격차 해결 / 더 많은 1단계 작업 필요}

실패와 주목할 만한 강점만 표시하고 통과하는 모든 체크박스를 나열하지 마세요.

격차가 있으면 특정 수정 사항을 제안하세요. 단순히 문제를 지적하지 말고 해결책을 제시하고 인간의 승인을 요청하세요.

ADR이 체크리스트를 통과하거나 인간이 명시적으로 격차를 수락할 때까지 마무리하지 마세요.

ADR 참조(읽기 워크플로)

에이전트는 ADR이 있는 코드베이스에서 변경 사항을 구현하기 전에 기존 ADR을 읽어야 합니다. 이것은 ADR 생성 워크플로의 일부가 아니라 모든 에이전트가 수행해야 하는 독립적인 작업입니다.

ADR을 참조해야 하는 경우

• 아키텍처(인증, 데이터 계층, API 설계, 인프라)를 건드리는 기능 작업을 시작하기 전에
• 코드에서 패턴을 발견하고 "왜 이렇게 되었을까?" 궁금할 때
• 기존 결정과 모순될 수 있는 변경을 제안하기 전에
• 인간이 "ADR을 확인하세요" 또는 "이것에 대한 결정이 있습니다"라고 말할 때
• 코드 주석에서 ADR 참조를 찾았을 때

ADR을 참조하는 방법

1. ADR 디렉터리 찾기. contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/ 확인. 인덱스 파일(README.md 또는 index.md)도 확인하세요.

2. 제목과 상태 스캔. 인덱스를 읽거나 파일 이름을 나열하세요. accepted ADR에 집중하세요 — 이것이 활성 결정입니다.

3. 관련 ADR을 완전히 읽으세요. 제목만 읽지 말고 컨텍스트, 결정, 결과, 비목표 및 구현 계획을 읽으세요. 구현 계획은 어떤 패턴을 따라야 하고 어떤 파일이 이 결정의 적용을 받는지 알려줍니다.

4. 결정을 존중하세요. 승인된 ADR이 "PostgreSQL 사용"이라고 말하면 이를 대체하는 새 ADR을 만들지 않고 MongoDB로 전환을 제안하지 마세요. 코드가 하는 일과 ADR이 말하는 것 사이에 충돌이 있으면 인간에게 알리세요.

5. 구현 계획을 따르세요. ADR이 적용되는 영역에서 코드를 구현할 때 해당 구현 계획에 지정된 패턴을 따르세요. 계획이 "모든 새 쿼리는 src/db/의 데이터 액세스 계층을 거쳐야 한다"고 말하면 그렇게 하세요.

6. 작업에서 ADR을 참조하세요. 코드 주석과 PR 설명에 ADR 참조를 추가하세요(아래 "코드 ↔ ADR 연결" 참조).

코드 ↔ ADR 연결

ADR은 그것이 규율하는 코드와 양방향으로 연결되어야 합니다.

ADR → 코드(구현 계획에서)

구현 계획 섹션은 특정 파일, 디렉터리 및 패턴을 명명합니다:

## 구현 계획

- **영향을 받는 경로**: `src/db/`, `src/config/database.ts`, `tests/integration/`
- **패턴**: 모든 데이터베이스 쿼리는 `src/db/client.ts`를 통해 수행

코드 → ADR(주석에서)

ADR의 안내를 받아 코드를 구현할 때 이를 참조하는 주석을 추가하세요:

// ADR: 테스트 데이터베이스에 better-sqlite3 사용
// 참조: docs/decisions/2025-06-15-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';

가볍게 유지하세요 — 진입점에 하나의 주석, 모든 줄에 하지 마세요. 목표는 발견성입니다: 미래의 에이전트가 이 코드를 읽을 때 근거를 찾을 수 있습니다.

이것이 중요한 이유

• src/db/에서 작업하는 에이전트는 해당 영역을 규율하는 ADR을 찾을 수 있습니다.
• ADR을 읽는 에이전트는 이를 구현하는 코드를 찾을 수 있습니다.
• ADR이 대체되면 코드 참조를 통해 업데이트해야 할 모든 코드를 쉽게 찾을 수 있습니다.

기타 작업

기존 ADR 업데이트

1. 의도 파악:

   • 수락 / 거부: 상태 변경, 최종 컨텍스트 추가.
   • 폐기: 상태 → deprecated, 대체 경로 설명.
   • 대체: 새 ADR 생성, 양방향 연결(이전 → 새, 새 → 이전).
   • 학습 추가: 날짜 스탬프와 함께 ## 추가 정보에 추가. 기록을 다시 쓰지 마세요.

2. 상태 변경에는 scripts/set_adr_status.js 사용(YAML 프론트 매터, 글머리 기호 상태 및 섹션 상태 지원).

수락 후 라이프사이클

ADR이 수락된 후:

1. 구현 작업 생성. 구현 계획의 각 항목과 결과의 각 후속 작업은 추적 가능한 작업(이슈, 티켓 또는 TODO)이 되어야 합니다.
2. PR에서 ADR 참조. PR 설명에 ADR 링크, 예: "contributing/decisions/2025-06-15-use-sqlite-for-test-database.md 구현."
3. 코드 참조 추가. 주요 구현 지점에 ADR 경로 주석을 추가하세요.
4. 검증 기준 확인. 구현이 완료되면 검증 체크박스를 살펴보세요. ## 추가 정보에 결과로 ADR을 업데이트하세요.
5. 트리거가 발생하면 재검토. ADR이 재검토 조건을 지정한 경우("X가 발생하면 재고"), 해당 조건을 모니터링하세요.

인덱스

리포지토리에 ADR 인덱스/로그 파일(종종 ADR 디렉터리의 README.md 또는 index.md)이 있으면 업데이트 상태를 유지하세요.

권장: scripts/new_adr.js --update-index가 수행하도록 하세요. 그렇지 않으면:

• 새 ADR에 대한 글머리 기호 항목을 추가하세요.
• 순서를 일관되게 유지하세요(번호가 매겨져 있으면 숫자 순, 슬러그면 날짜 또는 알파벳 순).

부트스트랩

ADR이 없는 리포지토리에 ADR을 도입할 때:

node /path/to/adr-skill/scripts/bootstrap_adr.js

이것은 디렉터리, 인덱스 파일 및 실제 내용이 포함된 첫 번째 ADR("아키텍처 결정 기록 채택")을 생성하여 팀이 ADR을 사용하는 이유를 설명합니다. 기계 판독 가능 출력에는 --json을 사용하세요. 디렉터리 이름을 재정의하려면 --dir을 사용하세요.

카테고리(대규모 프로젝트)

ADR이 많은 리포지토리의 경우 하위 디렉터리별로 구성하세요:

docs/decisions/
  backend/
    2025-06-15-use-postgresql.md
  frontend/
    2025-06-14-adopt-react-query.md
  cross-cutting/
    2025-06-13-logging-strategy.md

이것은 필수가 아닙니다. 많은 수의 ADR이 있고 검색 가능성이 문제가 될 때만 수행하세요.

ADR 상태 및 수명

각 ADR에는 다음 중 하나의 상태가 있습니다:

• proposed: 초안, 아직 결정되지 않음
• accepted: 공식적으로 승인됨, 구현 안내
• rejected: 승인되지 않음, 왜 기록이 유용함
• deprecated: 더 이상 권장되지 않음, 대체 경로가 설명되어야 함
• superseded: 새 ADR로 대체됨, 새 ADR에 대한 참조 포함

상태는 다음 위치에 있을 수 있습니다:

• YAML 프론트 매터(템플릿 adr-simple.md 및 adr-madr.md에서):

  ---
  status: accepted
  date: 2025-06-15
  ---
  

• 첫 번째 수준 제목 뒤의 글머리 기호(대체 템플릿에서):

  # 제목
  
  - 상태: 제안됨
  - 날짜: 2025-06-15
  

• ## 상태 섹션(더 오래된 ADR 또는 자유 형식 파일에서):

  ## 상태
  
  수락됨
  

일관성을 유지하세요. 기존 ADR이 사용하는 스타일을 따르세요.

추가 정보

다음이 포함될 수 있습니다:

• 구현 후 학습한 내용(날짜 스탬프 포함)
• 관련 PR 또는 이슈에 대한 참조
• 해당되는 경우 거부된 대안에 대한 추가 메모
• 변경 로그 항목

이 섹션은 ADR의 수명 동안 성장합니다. 핵심 결정(컨텍스트, 결정, 결과)을 변경하지 마세요 — 대신 새 ADR을 만드세요.

참조

ADR 템플릿

핵심 템플릿:

• assets/templates/adr-simple.md — 대부분의 ADR에 사용(간단한 트레이드오프, 하나의 명확한 승자)
• assets/templates/adr-madr.md — 구조화된 옵션 분석이 필요할 때 사용(여러 옵션, 명시적 드라이버 및 트레이드오프)

템플릿 변형 참조: references/template-variants.md는 언제 무엇을 사용할지 안내합니다.

스크립트

• scripts/new_adr.js — 올바른 디렉터리, 파일명 및 템플릿 선택으로 새 ADR 생성
• scripts/set_adr_status.js — YAML 프론트 매터, 글머리 기호 또는 제목 상태 업데이트
• scripts/bootstrap_adr.js — ADR이 없는 리포지토리 초기 설정

모든 스크립트는 --help를 지원합니다.

리소스

• assets/templates/ — ADR 템플릿(simple, madr)
• references/review-checklist.md — 에이전트 준비 상태 체크리스트
• references/template-variants.md — 템플릿 선택 가이드
• examples/ — 이 기술로 생성된 예시 ADR