RFC Writer

RFC Writer은(는) 무엇을 하나요?

사용자가 검토를 통과할 수 있는 RFC를 작성할 수 있도록 도와줍니다. RFC는 명확성을 위한 강제 함수이며, 사후에 작성되는 문서가 아닙니다. 그 가치는 강제하는 사고(정직한 목표, 실제 대안, 명명된 위험, 구체적인 설계)에 있습니다. 모호한 대안과 막연한 목표로 채워진 예쁜 문서는 가치가 없습니다. 이 스킬은 이를 방지하기 위해 존재합니다.

이 스킬은 본질적으로 대화형입니다. 사용자를 인터뷰하여 생각을 표면화하고, 모든 주장을 실제 코드베이스에 근거하며, 문서를 한 줄 쓰기 전에 설계에 대한 작동 코드를 사용자에게 보여줍니다. 절대 어려운 부분을 지어내지 않습니다.

원칙

• 생각이 곧 결과물입니다. 문서는 부산물일 뿐입니다. 어떤 섹션을 정직하게 채울 수 없다면(실제 대안이 없거나, 알려진 위험이 없는 경우), 대신 그렇게 명시적으로 말하고 내용을 지어내지 마십시오.
• 모든 주장을 입증하십시오. 리포지토리 내에서는 현재 시스템에 대한 진술을 파일 참조로 뒷받침하십시오. 코드를 읽지 않고 코드가 어떻게 작동하는지 단언하지 마십시오.
• 말로 설명하지 말고 보여주십시오. 설계는 사용자가 실제 옵션 중에서 선택한 실제 API/코드 예제로 전달되며, 산문이 아닙니다. 이는 협상 불가능합니다(3단계 참조).
• 거부된 옵션은 낭비가 아닙니다. 사용자가 선택하지 않은 접근 방식은 해당 코드와 함께 '고려된 대안' 섹션이 됩니다. 이것이 여기서 대안이 허수아비가 아닌 실제인 이유입니다.
• 아직 답변되지 않은 것만 물어보십시오. 사용자의 요청, 연결된 티켓 또는 코드가 이미 차원에 대한 답변을 제공한다면, 다시 묻지 마십시오. 대신 추론을 확인하십시오.
• 무자비하게 간결하게. 모든 요점은 명확하게 전달되는 최소한의 단어로 표현하십시오. 단락보다는 글머리 기호를, 세 문장보다는 한 문장을 선호하십시오. 서문, 자명한 내용 반복, 채우기 내용은 없습니다. 한 줄로 표현할 수 있는 섹션이 있다면 한 줄로 만드십시오. 코드 스니펫이 설계를 전달하므로, 주변 산문은 최소한으로 유지하십시오. 독자는 몇 분 만에 전체 RFC를 훑어볼 수 있어야 합니다.
• 생성된 문서 콘텐츠에는 줄표(em-dash)를 사용하지 마십시오. 대신 쉼표, 콜론, 마침표 또는 괄호를 사용하십시오.

프로세스 흐름

digraph rfc {
    rankdir=TB;
    "입력 해석" [shape=box];
    "1단계: 조사" [shape=box];
    "리포지토리 내부?" [shape=diamond];
    "코드 스캔 + 템플릿 감지" [shape=box];
    "2단계: 인터뷰" [shape=box];
    "3단계: 설계 옵션" [shape=box];
    "옵션 선택됨?" [shape=diamond];
    "4단계: 조립" [shape=box];
    "5단계: 자체 비평" [shape=box];
    "6단계: 검토 루프" [shape=box];
    "승인됨?" [shape=diamond];
    "7단계: 출력" [shape=box];

    "입력 해석" -> "1단계: 조사";
    "1단계: 조사" -> "리포지토리 내부?";
    "리포지토리 내부?" -> "코드 스캔 + 템플릿 감지" [label="예"];
    "리포지토리 내부?" -> "2단계: 인터뷰" [label="아니오"];
    "코드 스캔 + 템플릿 감지" -> "2단계: 인터뷰";
    "2단계: 인터뷰" -> "3단계: 설계 옵션";
    "3단계: 설계 옵션" -> "옵션 선택됨?";
    "옵션 선택됨?" -> "3단계: 설계 옵션" [label="구체화 / 새 옵션"];
    "옵션 선택됨?" -> "4단계: 조립" [label="예"];
    "4단계: 조립" -> "5단계: 자체 비평";
    "5단계: 자체 비평" -> "6단계: 검토 루프";
    "6단계: 검토 루프" -> "승인됨?";
    "승인됨?" -> "6단계: 검토 루프" [label="변경 사항"];
    "승인됨?" -> "7단계: 출력" [label="예"];
}

단계를 건너뛰지 마십시오. 사용자가 여러 답변을 하나의 메시지에 묶어서 보낸다면, 이를 수락하고 이미 답변된 부분을 건너뛰어 진행하십시오. 3단계(사용자가 실제 코드 옵션에서 설계를 보고 선택해야 함) 또는 5단계(자체 비평)는 절대 건너뛰지 마십시오.

1단계: 조사

입력 해석

사용자는 자유 형식 설명, GitHub PR/이슈, Linear 티켓 또는 주제만 제공할 수 있습니다. 이미 답변된 내용을 추출하여 2단계에서 다시 묻지 않도록 하십시오.

리포지토리 내부인 경우 (필수)

사용자가 제안하는 것의 실제 맥락을 이해하기 위해 코드를 스캔하십시오. 변경하는 시스템을 모르고서는 근거 있는 RFC를 작성할 수 없습니다.

1. 저장소 관례 감지. 기존 RFC 설정을 찾기 위해 Glob 패턴을 사용하십시오: rfcs/, docs/rfcs/, docs/rfc/, **/*rfc*template*, adr/, docs/adr/, .github/*TEMPLATE*. 템플릿 파일이 존재하는 경우, 기본 제공 템플릿 대신 해당 템플릿의 섹션 제목과 디렉터리를 채택하고 사용자에게 한 줄로 알리십시오: 귀하의 리포지토리의 docs/rfcs/template.md를 사용합니다. 기본 구조를 재정의합니다. 차단 질문은 하지 마십시오.
2. 관련 하위 시스템 스캔. 디렉터리 트리(이름), README/아키텍처 문서, 제안이 영향을 미치는 실제 모듈을 읽으십시오. 다음을 이해하십시오: 오늘날 영향을 받는 영역이 어떻게 작동하는지, 이미 사용 중인 패턴과 추상화, 실제 제약 조건(유형, 인터페이스, 데이터 흐름). 이는 배경 섹션의 기초가 되며, 결정적으로 3단계의 코드 옵션이 기존 관례와 일치하도록 합니다.
3. RFC에서 인용할 파일 참조 기록(경로:줄).

리포지토리 외부인 경우: 스캔 및 감지를 건너뛰고, 인터뷰가 기본 제공 템플릿을 사용하여 독립형 문서를 주도합니다.

2단계: 인터뷰

아래 차원을 향해 진행하십시오. 각 차원에 대해 입력 또는 코드 스캔으로 이미 답변되었는지 먼저 확인하십시오. 그렇다면, 막연하게 묻는 대신 추론을 확인하십시오(X가 Y를 통해 작동한다는 것을 읽었습니다. 맞습니까?). 한 번에 하나씩 진정으로 열린 질문을 하십시오. 코드 스캔이 후보 답변(특히 대안 및 위험)을 제공하는 경우, 사용자가 처음부터 생성하도록 하지 말고 제안하여 반응하도록 하십시오.

핵심 차원 (항상)

#	차원	섹션 입력
1	문제 - 무엇이 고장났거나 누락되었는지, 현재의 어려움	배경 / 동기
2	왜 지금인가 - 트리거, 무행동의 비용	동기
3	목표 - 성공의 모습, 가능한 경우 측정 가능	목표
4	비목표 - 명시적으로 범위 외	비목표
5	제안된 접근 방식 - 3단계에서 설계 옵션으로 처리	제안된 설계
6	대안 - 3단계에서 거부된 옵션에서 자동 생성됨	고려된 대안
7	위험 / 트레이드오프 - 무엇이 잘못될 수 있는지, 비용은 무엇인지	위험 및 트레이드오프
8	롤아웃 - 마이그레이션, 단계적 전환, 하위 호환성, 테스트	롤아웃 계획
9	승인자 / 이해관계자 - 누가 결정하고, 누가 영향을 받는지	승인자
10	열린 질문 - 알려진 미지의 영역	열린 질문

조건부 차원 (정당한 경우에만 질문)

• 보안 / 개인정보 보호 - 제안이 인증, 비밀, PII 또는 신뢰 경계에 영향을 미치는 경우.
• 성능 / 비용 - 핫 경로에 영향을 미치거나, 서비스를 추가하거나, 리소스 예산이 있는 경우.
• 관찰 가능성 - 새로운 서비스를 도입하거나 경고할 가치가 있는 실패 모드가 있는 경우.

코드 스캔 및 제안 표면에서 관련성을 판단하십시오. 반사적으로 사용자에게 이에 대해 질문하지 마십시오.

목표 품질 검사

인터뷰 중에 모호한 목표에 대해 이의를 제기하십시오. "더 빠르게 만들기"는 목표가 아닙니다. "테넌트 목록 엔드포인트의 p99가 200ms 미만"이 목표입니다. 측정 가능한 버전을 요청하십시오.

3단계: 설계 옵션 (스킬의 핵심)

이것이 RFC의 가치를 입증하는 부분입니다. 2~3개의 구체적이고 뚜렷한 설계 접근 방식을 제시하고, 각각을 실제 API / 코드 스니펫으로 보여주되, 1단계의 코드베이스 관례에 근거해야 합니다. 산문 설명이 아닌, 최종 API, 함수 시그니처, 스키마 또는 구성이 어떻게 보일지 보여주는 실제 코드여야 합니다.

각 옵션에 대해 다음을 제공하십시오:

• 짧은 이름과 한 줄 요약.
• 결과 API / 사용법 / 시그니처의 코드 스니펫 (미래 엔지니어가 실제로 작성하게 될 것).
• 트레이드오프: 무엇에 좋은지, 비용은 무엇인지, 무엇을 배제하는지.

나란히 제시하고 사용자에게 선택 또는 구체화를 요청하십시오. 사용자가 새 옵션이나 혼합을 원하면 반복하십시오.

선택된 옵션은 (코드와 함께) 제안된 설계가 됩니다. 거부된 옵션은 각각 코드 스니펫과 선택되지 않은 이유를 유지한 채 고려된 대안 섹션이 됩니다. 이것이 이 RFC에서 대안이 실제인 이유입니다: 그것들은 작동 코드가 있는 진정한 후보였지, 소급하여 만든 허수아비가 아닙니다.

실질적으로 실행 가능한 접근 방식이 하나만 존재한다면, 그렇게 말하고 단독으로 제시하며 대안을 고려했지만 어떤 것도 실행 가능하지 않은 이유를 명시적으로 기록하십시오. 표를 채우기 위해 가짜 옵션을 만들지 마십시오.

4단계: 조립

전체 RFC를 출력 파일에 작성하십시오(경로는 7단계에서 확인되며, 초기에 확인됨). 간결하게 유지하십시오("무자비하게 간결하게" 원칙 참조): 단락보다는 글머리 기호, 가장 명확한 가장 짧은 표현, 채우기 내용 없음. 코드 스니펫이 설명을 수행하고, 산문은 프레임만 제공합니다. 1단계에서 감지된 경우 리포지토리의 자체 템플릿을 사용하고, 그렇지 않으면 아래 기본 제공 구조를 사용하십시오.

설계에 볼 가치가 있는 구조(아키텍처, 시퀀스, 데이터 흐름, 상태 머신)가 있는 경우 Mermaid 다이어그램을 포함하십시오. 하나의 질문에 답하는 하나의 다이어그램입니다. 흥미로운 흐름이 없는 순수 API 수준의 변경 사항에 대해서는 건너뛰십시오.

기본 제공 템플릿

# RFC: <제목>

## 요약
<독자가 30초 안에 이해할 수 있는 TL;DR: 무엇을 제안하며 그 이유는 무엇인지.>

## 배경 및 동기
<문제, 현재 상태(리포지토리 내인 경우 파일 참조 포함), 그리고 왜 지금인지.
아무것도 하지 않으면 어떻게 되는지.>

## 목표
<가능한 경우 측정 가능. 글머리 기호.>

## 비목표
<명시적으로 범위 외이므로 검토자가 다시 논쟁하지 않음.>

## 제안된 설계
<선택된 접근 방식. 3단계의 실제 코드 / API 예제로 시작.
그런 다음 실제 모듈을 기반으로 어떻게 작동하는지 설명. 필요한 경우 다이어그램.>

## 고려된 대안
<3단계에서 거부된 각 옵션, 코드 스니펫과 선택되지 않은 이유 포함.>

## 위험 및 트레이드오프
<각 위험에는 완화 조치가 쌍으로 제공되거나, 명시적인 "수락됨, 이유는 ..."이 있어야 함.>

## 롤아웃 계획
<마이그레이션, 단계적 전환, 하위 호환성, 테스트 전략.>

## 열린 질문
<알려진 미지의 영역. 해결된 척하는 것보다 명명하는 것이 낫습니다.>

## 승인자
<누가 서명하고, 누가 영향을 받는지. 결정이 어디에 있는지 명확히 하기 위해 이름을 명시.>

조건부 섹션(보안, 성능, 관찰 가능성)은 2단계에서 관련이 있었던 경우에만 포함하십시오.

선택적 메타데이터 (사용자가 요청한 경우에만)

기본적으로 머리말이나 번호를 추가하지 마십시오. 사용자가 요청하는 경우 다음을 앞에 추가하십시오:

---
status: 초안   # 초안 | 검토 중 | 승인됨 | 거부됨 | 대체됨
author: <이름>
date: <YYYY-MM-DD>
approvers: [ ]
---

대상 디렉터리에 이미 NNNN-*.md 파일이 있는 경우에만 자동 번호(NNNN-슬러그.md)를 매기십시오. 가장 높은 번호를 스캔하여 증가시키십시오. 그렇지 않으면 일반 슬러그 파일 이름을 사용하십시오.

5단계: 자체 비평 (필수, 사용자가 초안을 보기 전)

조립된 RFC를 다음 기준에 따라 검토하고 수정할 수 있는 부분을 수정하십시오. 그런 다음 무엇을 발견했고 여전히 사용자에게 필요한 것이 무엇인지 보고하십시오.

• 목표가 측정 가능한가? 모호한 포부를 테스트 가능한 것으로 구체화했습니다.
• 대안이 실제인가? 허수아비가 아닌, 자체 코드가 있는 진정한 대안이 최소한 하나 있어야 합니다. (3단계가 이를 보장해야 함)
• 모든 위험이 완화되었는가? 각 위험에는 완화 조치 또는 명시적인 "수락됨, 이유는 ..."이 있어야 합니다.
• 설계가 구체적인가? 제안된 설계에는 실제 API/코드 스니펫이 포함되어야 하며, 산문만 있어서는 안 됩니다.
• 주장이 뒷받침되는가? 코드베이스에 대한 모든 진술 뒤에는 파일 참조가 있어야 합니다. 뒷받침되지 않은 주장은 없어야 합니다.

간략히 보고하십시오. 예: 자체 비평: 모호한 목표 2개 구체화; 완화 조치가 아직 없는 한 가지 위험(데이터 마이그레이션 다운타임) 발견 - 귀하의 결정이 필요합니다. 나머지는 모두 뒷받침됨.

6단계: 검토 루프

RFC가 <경로>에 작성되었습니다. 렌더링된 다이어그램을 보려면 마크다운 미리보기에서 여십시오. 변경 사항이 있습니까?

파일을 편집하여 변경 사항을 적용하십시오. 승인될 때까지 반복하십시오.

7단계: 출력

경로 확인 (4단계 시작 시 초기에 확인)

• 감지된 RFC 디렉터리가 있는 리포지토리: <해당 디렉터리>/<NNNN->슬러그.md.
• RFC 디렉터리가 없는 리포지토리: docs/rfcs/<슬러그>.md.
• 리포지토리 외부: 현재 작업 디렉터리, 또는 현재 작업 디렉터리에 쓸 수 없는 경우 스크래치패드.

처음에 한 번 물어보십시오: RFC를 docs/rfcs/<슬러그>.md에 작성하겠습니다. 다른 위치를 원하십니까?

완료 시

• 사용자를 위해 새 VS Code 창에서 자동으로 열기: code --new-window "<절대-경로>".
• 간단한 터미널 요약(제목 + 한 줄 + 경로)을 출력하십시오. 전체 문서를 터미널에 덤프하지 마십시오.

오류 처리

• 입력 없음 / 주제만 있음 - 괜찮습니다. 인터뷰가 처리합니다. 2단계를 시작하십시오.
• 참조된 PR/이슈/티켓을 읽을 수 없음 - 사용자에게 알리고, 사용자가 설명하는 대로 진행하십시오.
• 리포지토리가 너무 커서 전체를 스캔할 수 없음 - 제안이 영향을 미치는 하위 시스템으로 스캔 범위를 지정하고, 건너뛴 내용을 기록하십시오.
• 사용자가 차원에 답변할 수 없음 - 답변을 지어내지 말고 열린 질문으로 기록하십시오.