ADR 기반 개발 (Develop with ADRs)

ADR을 사용한 개발

필수 첫 단계: 충돌 확인

도메인을 묻거나, 에이전트를 생성하거나, 코드를 조사하거나, 변경을 수행하기 전에 번들된 읽기 전용 스크립트를 실행하세요:

python3 <절대-스킬-디렉토리>/scripts/check_conflicting_skills.py --project <저장소-경로>

플레이스홀더를 실제 경로로 해결하고 필요에 따라 경로를 인용하세요. 세션의 사용 가능한 스킬 카탈로그에 있는 모든 이름을 반복되는 --available-skill 인수로 전달하되, 클라우드 전용 및 플러그인으로 한정된 이름을 포함하세요. 비표준 스킬 디렉토리는 --root로 추가하고, 관련 중첩 디렉토리 심볼릭 링크의 대상을 명시적으로 추가하세요. 이 스크립트는 로컬 스킬 파일과 카탈로그 항목을 발견하지만, 해당 명령어를 로드하거나 설치를 변경하지는 않습니다.

• grill-me와 spec-first를 충돌 스킬로 취급하며, 대소문자, 공백, 밑줄, 하이픈 변형(예: Grill Me 또는 spec_first)을 포함합니다.
• 종료 코드 0은 검사 범위 내에서 충돌이 발견되지 않았음을 의미합니다. 종료 코드 1은 충돌이 발견되었음을 의미하며, 이는 스크립트 실패가 아닙니다. 종료 코드 2는 발견이 불완전함을 의미합니다: 오류와 범위 제한을 보고하고, 가능한 경우 해결한 후 다시 실행하세요. 범위가 불완전한 경우 모든 스킬이 확인되었다고 주장하지 마세요.
• 일치하는 항목이 있으면 이 워크플로우 내에서 해당 스킬의 사용을 비활성화하고 계속 진행하기 전에 사용자에게 해당 언어로 경고하세요: 감지된 스킬의 이름을 말하고 현재 워크플로우에 대해서만 비활성화되었음을 설명하세요. 전역 제거 또는 계정 설정 변경을 암시하지 마세요. 이러한 워크플로우 제외에 대한 추가 승인은 필요하지 않습니다.
• 제외된 스킬을 호출하거나, 해당 명령어를 따르거나, 작업을 위임하지 마세요. 제외 사항을 코디네이터, 아키텍트, 구현자에게 적용하고 모든 에이전트 핸드오프 시 제외 목록을 전달하세요. 이 워크플로우의 자체 명확화 및 승인 단계를 사용하세요.
• 스크립트는 충돌을 감지하고, 코디네이팅 에이전트는 제외를 강제합니다. 세션 카탈로그에 파일에 접근할 수 없더라도 스킬이 드러나면 해당 스킬도 제외하세요. 스크립트를 실행할 수 없으면 해당 제한을 보고하고 성공적인 스캔을 주장하지 않고 알려진 제외를 적용하세요.
• 세션을 재개하거나 사용 가능한 스킬이 변경된 후에는 다시 실행하세요. 이 확인의 일부로 설치된 스킬을 삭제, 이름 변경 또는 전역 비활성화하지 마세요.

시작 및 역할

1. 워크플로우를 시작하기 전에 아키텍트가 집중해야 할 도메인을 물어보세요. 비즈니스 또는 기술 도메인을 수락합니다. 명시적으로 제공된 도메인이 있으면 다시 묻지 않고 재사용하세요.
2. 선택한 도메인에 대해 전체 세션 동안 별도의 아키텍트 에이전트를 생성하세요. 이 규칙, 도메인, 저장소 경로 및 알려진 컨텍스트를 제공하세요. 아키텍트가 사용자에게 해결할 문제를 묻게 하세요; 메인 에이전트는 질문과 답변을 중계할 수 있습니다. 문제가 이미 제공된 경우 누락된 정보만 물어보세요.
3. 메인 에이전트가 대화, 문서 및 컨텍스트 핸드오프를 조정하게 하세요. 아키텍트가 조사, 설계, ADR 유지 관리 및 결과를 독립적으로 검증하게 하세요. 별도의 구현 에이전트가 승인된 결정을 구현하고 증거를 준비하게 하세요. 아키텍트와 구현자 역할을 결합하지 마세요.
4. 환경의 기본 분리 에이전트 기능을 사용하세요: Codex의 서브에이전트, Claude Code의 사용 가능한 에이전트/태스크 기능. API를 발명하거나 단일 에이전트가 역할을 전환하는 것을 독립적 검증으로 제시하지 마세요. 별도 에이전트를 사용할 수 없는 경우 제한을 설명하고 사용자에게 적합한 환경을 선택하도록 요청하세요. 조사는 계속될 수 있지만 이 워크플로우에 따른 구현은 시작되어서는 안 됩니다.
5. 컨텍스트 손실 후에는 문서와 코드에서 상태를 복원하세요. 새 아키텍트를 생성해야 하는 경우 원래 에이전트가 살아남았다고 주장하지 말고 해당 도메인과 책임을 복원하세요.

조사 및 결정

• 아키텍트가 프로젝트 지침, 코드, 관련 ADR 및 증거를 읽고 문제와 제약 조건을 명확히 하게 하세요. 코드를 조사하고 문제를 명확히 하기 전에 ADR을 생성하지 마세요. 아직 코드가 없으면 해당 사실을 기록하고 사용 가능한 자료를 조사하세요.
• 현재 결정과의 충돌을 식별하세요. 먼저 충돌을 사용자에게 제시하고 결정을 요청하세요; 응답 후에만 새 ADR을 준비하세요. 대체품을 준비할 권한은 이를 구현할 승인이 아닙니다.
• 템플릿을 사용하여 docs/adr/에 ADR을 작성하세요. 간단한 문제 설명, 제안된 해결책, 근거 및 안정적인 ID가 있는 검증 가능한 수락 기준을 포함하세요. 초기 상태를 accepted-for-discussion으로 설정하세요.
• 독립적인 결정은 별도의 ADR로 분리하고 종속성을 명시적으로 기록하세요. 종속성 또는 대체 주기를 도입하지 마세요.
• 특정 ADR 또는 열거된 ADR 세트를 구현에 대한 명시적 사용자 승인을 위해 제시하세요. 침묵, 무언가를 구축하라는 일반적인 요청 또는 조사 권한으로부터 승인을 유추하지 마세요.
• 사용자의 응답, 날짜 및 승인된 문서 버전을 기록하세요. 명시적 승인 후에만 accepted-for-work로 설정하세요. 열거된 ADR 세트의 명시적 승인을 허용하세요.

구현

• ADR이 종속된 모든 ADR이 완료된 후에만 해당 ADR의 구현을 시작하세요. 전체 세트가 이미 승인된 경우에도 마찬가지입니다.
• 구현자에게 ADR, 기준, 종속성 및 제약 조건을 제공하세요. 승인된 결정의 범위 내에서 구현을 요구하세요.
• 구현이 불가능하거나 결정 또는 기준을 변경해야 하는 경우, 영향을 받는 작업을 중단하고 문제를 아키텍트에게 반환하세요. 독립적으로 승인된 작업은 계속될 수 있습니다.
• 승인 후에는 해결책 설명이나 수락 기준을 절대 변경하지 마세요. 변경 사항은 별도의 승인을 받은 새 ADR에 기록하세요.
• 구현자가 docs/evidence/에 증거를 준비하게 하세요: 각 기준에 대한 결과, 명령어 및 재현 지침, 그리고 검증된 커밋 또는 정확한 코드 버전. 테스트된 버전을 미래의 커밋으로 대체하지 마세요. 커밋되지 않은 변경 사항의 경우 저장된 diff와 확인된 파일의 식별자 또는 해시를 포함하세요.

독립적 검증 및 완료

• 아키텍트가 직접 검사를 실행하고 모든 수락 기준에 대해 실제 결과를 비교하게 하세요. 구현자의 보고서 및 코드 검사는 실행을 대체하지 않습니다.
• 명령어, 환경, 결과, 로그 링크 및 검증된 버전을 증거에 보존하세요. 실행되지 않았거나, 차단되었거나, 실패한 검사는 정직하게 표시하세요. 확인되지 않았거나 충족되지 않은 기준으로 ADR을 완료하지 마세요.
• 구현이 검증에 실패했지만 ADR이 여전히 유효한 경우, 먼저 결과와 구체적인 수정 범위를 사용자에게 제시하고 권한을 요청하세요. 응답 전에 수정을 위임하거나 수행하지 마세요. 권한을 받은 후 구현자가 문제를 수정하고 아키텍트가 다시 검증하게 하세요. 또 다른 검증 실패는 다음 수정 주기에 대해 새로운 권한이 필요합니다.
• 실패로 인해 새로운 아키텍처 결정이 필요한 경우 조사 및 새 ADR 절차로 돌아가세요.
• 아키텍트만이 모든 기준의 성공적인 독립적 검증 후에 completed를 설정할 수 있도록 허용하세요. 증거 문서에 대한 링크가 필요합니다. ADR을 완료하는 데 추가 사용자 승인이 필요하지 않습니다.

상태 및 이력 보존

정확히 네 가지 표준 status 값을 사용하세요. 아래의 러시아어 레이블은 원래 의미를 식별합니다. 레거시 문서를 조용히 다시 작성하지 말고 기존 프로젝트 이력을 보존하세요.

상태	원래 레이블	조건
accepted-for-discussion	принято к обсуждению	논의 또는 승인을 기다리는 조사된 제안
accepted-for-work	принято к работе	사용자가 특정 ADR을 명시적으로 승인함
completed	завершен	아키텍트가 모든 기준을 독립적으로 검증함; 증거가 연결됨
rejected	отклонено	새로운 승인된 ADR과 거부 근거/증거가 존재함

• ADR 또는 증거 문서를 삭제하거나 해당 ID를 재사용하지 마세요. 승인 전에는 중요한 변경 사항을 기록하면서 초안 개선을 허용하세요.
• 승인 후에는 해결책 본문과 기준을 변경할 수 없게 유지하세요. 추가된 이력 항목과 함께 현재 상태 및 링크 업데이트를 허용하세요. 이전 항목, 증거 및 검증 결과를 보존하세요. 실패한 검사를 통과 결과로 덮어쓰지 마세요.
• 사용자가 기존 ADR을 대체할 ADR을 명시적으로 작업 승인하는 순간, 기존 ADR이 완료된 경우를 포함하여 이전 ADR을 거부하세요. 즉시 이전 ADR을 대체 ADR 및 별도의 거부 근거 문서에 연결하세요. 이는 이전 결정이 왜 거부되었는지 증명합니다. 새 구현이 작동한다는 것을 증명하지는 않습니다.
• 이전 완료, 해당 날짜, 버전 및 증거를 보존하세요. 대체품이 아직 구현되지 않았을 수 있음을 명시적으로 기록하세요. 문서를 거부한다고 해서 작동 중인 코드가 자동으로 제거되지는 않습니다.
• 새 결정 없이 ADR을 거부하지 마세요. 사용자가 대체품을 선택하지 않은 경우 현재 상태를 유지하고 논의 항목을 추가하세요. 상태 전환을 가능하게 하기 위해 대체품을 발명하지 마세요.
• 종속성이 거부되거나 대체되면 영향을 받는 작업을 일시 중지하고 아키텍트가 영향을 평가하게 하세요. 승인된 결정을 조용히 재연결하지 마세요.

문서 그래프

• 문서를 생성하기 전에 템플릿을 읽고, 새 환경을 사용할 때는 이식성 지침을 읽으세요.
• ADR을 docs/adr/ADR-0001-short-slug.md로, 증거를 docs/evidence/EVID-0001-short-slug.md로 저장하세요. 기존 이력을 고려하여 다음 사용 가능한 번호를 선택하세요. 이전 문서의 번호를 다시 매기지 마세요.
• 명시적 상대 Markdown 링크와 관계 유형을 사용하세요: replaces / replaced_by, depends_on / required_by, extends / extended_by, 그리고 evidence / proves. 역링크를 유지하고 증거가 구현 또는 거부 이유를 증명하는지 식별하세요.
• ADR과 증거를 그래프의 문서로 취급하세요. 별도의 그래프 데이터베이스는 필요하지 않습니다. 핸드오프 시 링크 대상, 역링크, 종속성 주기 부재 및 상태 조건을 확인하세요.
• 각 단계가 끝날 때 사용자를 기다리는 경우 ADR 상태, 결과, 문서 링크 및 필요한 특정 결정을 보고하세요. 단순히 승인되었거나 구현되었지만 검증되지 않은 작업을 완료된 것으로 설명하지 마세요.