EvolveHQ/docflow

add-convention

컨벤션을 추가합니다 — 하지만 추가할 가치가 있는지와 어디에 속하는지 먼저 평가한 후에 추가합니다. 이 스킬은 게이트키퍼이자 라우터이지, 속기사가 아닙니다.

0단계 — 사전 조건 및 맥락

1. 레포지토리가 부트스트랩되었는지 확인합니다.
2. CONVENTIONS.md와 AGENTS.md를 전체 읽어 기존 규칙과의 중복을 감지하고 적합성을 판단합니다.

0.5단계 — 평가 (먼저 실행)

공유 평가 프로토콜을 실행합니다. 분류(1단계) 및 라우팅(2단계) 질문은 이 프로토콜 아래에서 수행됩니다.

• 먼저 제공된 답변을 재사용합니다. 요청 또는 현재 세션에서 이미 제공된 관련 선택 사항(깊이 포함)을 처리된 것으로 간주합니다. 다시 묻지 않고 요약하며, 기본값이 명시적 선택을 대체하지 않습니다. 모든 중요한 선택 사항이 제공되면 진행합니다. 중요한 누락 또는 충돌하는 선택 사항에 대해서만 질문합니다. 레포지토리 환경 설정 자체는 현재 답변 또는 실행 허가가 아닙니다.

• 해결되지 않은 선택 사항에 대한 깊이 선택기. 깊이가 제공되지 않고 선택 사항이 남아 있는 경우, 이 평가를 얼마나 깊이 수행할지 질문합니다: 간편 — 모든 선택 사항이 권장 기본값을 사용하며, 파생 가능한 기본값이 없는 질문(자유 형식 필수 사항)만 여전히 질문합니다; 안내 — 아래에 높은 영향으로 표시된 질문과 자유 형식 필수 사항만 질문합니다; 전체 — 아래의 모든 질문. 레포지토리의 CONVENTIONS.md에 Assessment depth:가 기록되어 있으면, 질문 시 권장 옵션으로 미리 선택합니다. 기록된 깊이는 절대 자동으로 적용되지 않습니다. 그렇지 않으면, 요청에 맥락이 거의 또는 전혀 없을 때 전체를 권장하고, 이미 완전히 지정된 경우 간편을 권장합니다. 어떤 질문에서든 운영자는 "여기서부터 기본값" 또는 "더 깊이 들어가기"라고 답할 수 있으며, 즉시 전환을 존중합니다.

• 질문을 한 번에 하나씩 하고, 각각 권장 옵션과 한 줄 설명을 제공하며 각 답변을 기다립니다.

• 구조화된 선택(단일 또는 다중 선택)을 사용합니다. 호스트가 구조화된 단일/다중 선택 질문 도구를 노출하면 이를 사용하고 권장 옵션을 표시합니다. 그렇지 않으면 일반 텍스트로 A/B/C 옵션을 나열하고 권장 옵션을 명시합니다. 자유 형식은 열거 가능한 집합이 불가능한 경우에만 사용합니다(예: 정확한 표현).

• 운영자가 결정합니다. 답변 없이 질문을 넘어가지 말고, 맥락 없이 호출될 때 범위를 추측하지 마십시오.

질문(요청이 이미 답변한 항목은 건너뜁니다):

1. 문서화할 가치가 있는가? — 예(반복적, 안정적, 테스트 가능) 또는 아니요(일회성, 중복, 변동 가능성 높음, 모호함). 권장: 1단계 분류에 따름. 이 질문이 나머지 질문의 관문 역할을 합니다. (높은 영향 — 안내 모드에서 질문.)
2. 위치 — AGENTS.md 하드 규칙 / CONVENTIONS.md 지침 / GLOSSARY.md 용어 / 실제로는 결정(new-adr 스킬로 넘김). 권장: 규칙의 성격에 따름(2단계 참조). (높은 영향 — 안내 모드에서 질문: 잘못된 위치는 이동하는 데 혼란을 초래함.)
3. 검증 게이트에서 강제? — 예 / 아니요. 권장: 아니요, 규칙이 기계적으로 확인 가능한 경우가 아니라면.
4. 표현 — 자유 형식(규칙 진술문 자체, 모든 깊이에서 질문).

1단계 — 평가: 문서화할 가치가 있는가?

분류를 적용합니다. 다음과 같은 경우 추가를 권장하지 않습니다:

• 기존 컨벤션에 (명시적 또는 암시적으로) 이미 포함된 경우 — 중복 대신 해당 컨벤션을 가리킵니다.
• 반복적인 결정이 아닌 일회성인 경우 — 문서화하면 노이즈가 추가됩니다.
• 변동 가능성이 높은 경우 — 성급한 규칙은 오래된 쓰레기가 됩니다.
• 작성된 대로 테스트 가능하거나 실행 가능하기에는 너무 모호한 경우.

다음과 같은 경우 추가를 권장합니다: 모호함으로 인해 재작업이 발생하는 반복적인 결정이고, 안정적이며, 추가 해석 없이 에이전트가 따를 수 있도록 명시할 수 있는 경우. 어떤 작업을 하기 전에 권장 사항과 이유를 명시하십시오.

2단계 — 라우팅: 어디에 속하는가?

위치를 결정하고 선택 이유를 설명합니다:

• 에이전트가 준수해야 하는 하드 규칙 → AGENTS.md §하드 규칙에 항목을 추가하고, 내용은 CONVENTIONS.md에 작성합니다. 불가침의 제약 조건에 사용합니다.
• 작성/프로세스 지침 → CONVENTIONS.md의 섹션. 정보를 제공하지만 게이트 역할은 하지 않는 "우리의 업무 방식"에 사용합니다.
• 공유 용어/정의 → GLOSSARY.md(없으면 생성 — 첫 번째 용어를 추가하면 용어집 계층이 활성화됨, 기록된 아티팩트 루트에 배치). 레포지토리의 CONVENTIONS.md §용어집을 읽고 실제로 선언된 규칙을 검사합니다. 표준 구조는 선택적 H1 제목과 선택적 소개 문단, 정확히 두 개의 열로 된 용어 | 정의 테이블입니다. 모든 용어는 자체 행입니다. 용어를 제목, 글머리 기호 또는 문단으로 기록하지 말고, 두 번째 테이블이나 다른 열 모양을 추가하지 마십시오. 이전 또는 관련 없는 용어집 규칙을 명시하는 §용어집은 이 테이블을 채택한 것이 아닙니다. 표준 모양을 사용하고, 이전 모양을 복사하는 대신 별도로 동의된 규칙 및 파일 마이그레이션을 위한 감사 스킬을 제공합니다. GLOSSARY.md가 없는 것은 유효한 상태로 남아 있습니다. 이 스킬은 용어가 실제로 추가되기 때문에 생성합니다.
• 실제로는 컨벤션이 아닌 결정(대안과 결과가 있는 아키텍처, 제품 또는 기술 선택) → 이것은 ADR입니다. 중단하고 new-adr 스킬을 제공합니다. 결정을 CONVENTIONS에 묻지 마십시오.

컨벤션이 분류/프로세스 규칙(예: 수신 작업 분류 방법)인 경우, 불가침 부분에 대해서만 AGENTS.md에 하드 규칙 항목을 포함하여 CONVENTIONS.md를 선호합니다.

3단계 — 초안 작성 및 확인

해당 파일에 대한 정확한 표현을 초안으로 작성합니다. 간결하고, 테스트 가능하며, 레포지토리의 언어를 사용합니다. Diff를 보여줍니다. 쓰기 전에 확인합니다.

4단계 — 작성 및 커밋

편집을 적용합니다. 컨벤션이 하드 규칙으로 승격되면 AGENTS.md와 CONVENTIONS.md가 일관성을 유지하는지 확인합니다. Conventional Commit (docs: ...). ADR이 수정되지 않았으므로 Rationale: 바닥글은 필요하지 않지만, 레포지토리의 계약에서 컨벤션 변경 시 이를 요구하는 경우 추가합니다.

용어집 추가 또는 확장. 아래 정의된 표준 구조와 선언된 규칙 검사를 사용합니다. 모양은 실행 간에 변경되어서는 안 됩니다.

• 규칙이 나온 곳. CONVENTIONS.md에 §용어집 섹션이 없는 경우(이전 레포지토리, 또는 규칙이 기록되기 전에 활성화된 계층), 위의 제품 기본 표준 규격으로 대체합니다: 선택적 # Glossary 제목과 소개 문단, 그 다음 하나의 Term | Definition 테이블. 해당 레포지토리에 대해 다른 모양을 만들지 말고, 관련 없는 컨벤션을 자동으로 편집하지 마십시오.
• 선언된 규칙 읽기. §용어집이 존재하면 실제로 선언된 내용을 읽습니다. 표준 두 열 Term | Definition 테이블을 설명하는 경우 따르고 명시적 요청 시에만 변경합니다. 다른 또는 이전 용어집 규칙(글머리 기호, 문단, 다른 열 모양)을 명시하는 경우, 레포지토리는 이 테이블을 채택하지 않은 것입니다. 이전 모양을 복사하지 말고, 규칙을 자동으로 다시 쓰지 마십시오. 용어에 표준 모양을 사용하고, 규칙과 파일을 함께 별도로 동의된 Diff로 다루는 감사 스킬의 마이그레이션을 제공합니다.
• 컨벤션 기록. §용어집이 없는 경우, 추가되는 용어와 별도로 확인된 편집으로 CONVENTIONS.md에 ## Glossary 섹션을 기록하여 실제 사용된 모양을 명시하는 것을 제공합니다. 해당 Diff를 보여주고 사용자가 수락하는 경우에만 작성합니다. 다른 CONVENTIONS.md 섹션을 다시 작성하거나 순서를 변경하여 공간을 만들지 말고, 사용자가 거부하는 경우 용어집은 표준을 유지하지만 CONVENTIONS.md는 변경하지 않은 상태로 둡니다.
• 파일 생성. 레포지토리에 필요한 선택적 # Glossary 제목과 짧은 소개 문단을 작성한 다음, 헤더가 Term | Definition이고 새 용어가 첫 번째 행인 단일 두 열 테이블을 작성합니다. 플레이스홀더 용어를 만들지 마십시오.
• 기존 파일 확장. 제목, 소개 문단, 항목 순서 및 모든 기존 행을 바이트 단위로 유지합니다. 새 용어를 하나의 새 행으로 추가합니다. 파일을 재구축, 재정렬 또는 재포맷하지 말고, 두 번째 테이블을 도입하지 마십시오.
• 앵커. 새 용어의 행이 수신 링크가 이미 사용하는 제목 앵커에서 도달 가능한 경우, 대상을 삭제하는 대신 해당 앵커를 행에 유지합니다. 앵커를 보존할 수 없으면 추측하는 대신 중단하고 플래그를 지정합니다.
• 의미 보존. 용어의 철자, 별칭, 링크 및 인라인 코드를 정확히 제공된 대로 유지합니다. 리터럴 파이프 |는 \|로 이스케이프합니다. 정의가 진정으로 여러 줄인 경우, 추가 행으로 넘어가는 대신 하드 브레이크를 위해 <br>과 함께 하나의 셀에 유지합니다.
• 중복 및 모호성. 용어가 이미 존재하는 경우, 기존 정의와 제안된 정의를 보여주고 업데이트할지 또는 기존 행을 그대로 둘지 질문합니다. 동일한 용어에 대해 절대 자동으로 병합, 대체 또는 두 번째 행을 추가하지 말고, 정의를 추측하지 마십시오.
• 비표준 파일. 기존 GLOSSARY.md가 글머리 기호, 문단, 제목 또는 혼합 모양인 경우, 경쟁 행을 추가하지 말고 용어 추가의 부작용으로 파일을 다시 쓰지 마십시오. 비표준 구조를 표면화하고 감사 스킬의 동의된 마이그레이션을 제공합니다. 사용자가 구체적인 Diff를 수락하는 경우에만 적용합니다. 거부된 마이그레이션은 사용자가 유지하는 대로 파일을 남깁니다.

수행된 규칙 및 전파를 명명합니다. 업데이트되지 않은 레포지토리를 나열합니다.

마감 보고

차단, 실패 및 중지된 실행을 포함한 모든 실행을 Status at a glance라는 제목의 섹션으로 종료하며, 다음 세 가지 레이블을 포함합니다:

• This run: 실제로 시도된 작업과 그 결과만 포함합니다. 각 검증 게이트의 정확한 출력과 종료 코드(시간 초과 또는 중단 포함)를 인용합니다.
• Overall: implemented, partially verified, verified, blocked, failed 또는 unknown. 통과된 하위 단계가 전체 통과를 의미하지 않습니다. 불완전하거나 누락된 증거는 성공이 될 수 없습니다.
• Yet to do: 모든 남은 작업, 해결되지 않은 발견, 검증, 정리 또는 필요한 입력. 전체 작업이 확인 가능하게 완료된 경우에만 None을 작성합니다. 예산이 종료되었다고 해서 작업을 생략하지 마십시오.

일상적인 진행 메시지는 블록이 필요하지 않습니다. 최종 결과는 간결하게 유지하고 PR에서 준비된 작업과 출시가 확인된 작업을 구분합니다.