스토리 워크스루 (Story Walkthrough)

스토리 워크스루 (Story Walkthrough)은(는) 무엇을 하나요?

사용자가 자신이 겪지 않은 문제를 이해하려고 합니다. 사용자는 컴포넌트, 용어, 또는 일이 발생하는 순서를 모릅니다. 조사 결과 목록이나 diff 요약은 도움이 되지 않습니다. 이야기는 다릅니다. 각 등장인물을 한 번씩 소개한 후, 각각이 하는 일을 순서대로 보여주며, 실패가 자연스럽게 이어지도록 합니다.

먼저 조사하십시오. 이야기는 그 뒤에 있는 사실만큼만 좋습니다. 따라서 코드, 로그, 티켓, 문서, 이력을 읽고 작성하십시오. 조사가 대화 중에 이미 이루어졌다면 반복하지 말고 재사용하십시오.

답변의 구조

코드를 알고 있다고 가정하지 않고 처음부터 전체 이야기를 제공한다는 한 문장으로 시작하십시오. 예: "코드를 모른다고 가정하고 처음부터 전체 이야기를 들려드리겠습니다." 그런 다음 다음 섹션을 사용하십시오. 말할 내용이 실제로 없는 섹션은 채우지 말고 건너뛰십시오.

등장인물 (The characters)

이야기에 필요한 모든 등장인물(컴포넌트, 클래스, 메시지, 타이머, 데이터, 그리고 프로세스의 경우 관련된 사람, 팀, 양식, 설정)을 소개하고 그 외에는 소개하지 마십시오. 각 등장인물에 굵은 글씨 이름을 지정하고, 그것이 무엇이고 이 이야기에서 무엇을 하는지 한두 문장으로 설명하십시오.

• 각 등장인물의 이름을 정확히 지정하고 코드에 연결하십시오. price_cache_key()를 file:line 링크와 함께 작성하고 "키 빌더"라고 쓰지 마십시오. 모호한 레이블은 독자가 멈추고 의미를 묻게 만듭니다. 등장인물이 여러 코드 조각(메서드와 그 주변 프레임워크 훅)에 걸쳐 있다면 여기에 명시하십시오. 코드 외부의 문제라면 대신 출처(문서와 단계, 양식 필드, 설정 경로)에 링크하십시오.
• 추상적인 메커니즘에 대해 하나의 물리적 비유를 선택하고 이야기 전체에 걸쳐 유지하십시오. 예를 들어, 메시지 헤더는 "봉투에 스테이플로 고정된 메모", 캐시는 "화이트보드", 잠금은 "열쇠"가 됩니다. 실제 이름 옆에 비유를 소개하여(예: "가격 캐시, 각 웹 서버 옆에 있는 화이트보드") 독자가 코드로 다시 매핑할 수 있게 하십시오. 도중에 비유를 바꾸거나 두 개를 쌓지 마십시오.
• 각 등장인물이 따르는 규칙을 등장인물 자신의 생각으로 기울임꼴로 표현하십시오: "오늘은 내 시계가 표시하는 날짜다." 버그와 프로세스 실패는 일반적으로 두 가지 합리적인 규칙이 충돌하여 발생하며, 이렇게 하면 나중에 그 충돌을 확인할 수 있습니다.

장 (Chapters)

시간 순서대로 무슨 일이 일어나는지 말하고, 각 단계를 하나의 장으로 만드십시오: ## 1장: 자정 전에 쇼핑객이 가격을 본다, ## 2장: 새 가격이 도착한다 등. 무슨 일이 일어나는지 알려주는 짧은 제목을 사용하십시오.

• 각 장을 짧게 유지하십시오: 몇 문장 또는 몇 개의 글머리 기호.
• 장의 핵심 세부 사항, 독자가 놓쳐서는 안 될 한 가지 사실을 굵게 표시하십시오 ("가져오기가 화이트보드의 잘못된 모서리를 지운다").
• 두 가지 일이 동시에 발생하면 그 자체로 장을 만들고 양쪽을 차례로 보여주십시오.
• 실패 장은 정확한 오류 메시지를 인용 블록으로 인용하고, 어떤 코드가 그것을 캐치하고 무엇을 로그하는지 말하십시오.

증상이 그렇게 보이는 이유 (Why the symptom looks the way it does)

실패 후에 관찰된 패턴(왜 처음 몇 시간 동안만, 왜 일부 서버에서만, 왜 재시작 후에만)을 설명하십시오. 이를 티켓이나 로그에 실제로 표시된 내용과 연결하십시오. 이것은 이야기가 올바른지 확인하는 검증이므로 유지하십시오.

문제가 실패가 아닌 리스크인 경우 (When the issue is a risk, not a failure)

때로는 이야기가 잘못될 수 있는 것(리뷰 의견, 잠재적 버그, "만약에")에 관한 것입니다. 아무것도 실패하지 않았으므로 이야기를 고정할 로그 줄이나 티켓 증상이 없습니다. 다르게 말하십시오. 인용된 오류를 본 독자는 그것이 발생했다고 가정하기 때문입니다.

• 아직 발생하지 않았다고 초기에 말하십시오. 시작 줄이나 첫 번째 장에서 이것이 로그나 테스트에서 발견된 것이 아니라 코드를 읽어서 발견된 가능한 실패라고 명시하십시오.
• 조건을 명확히 하십시오. 실패 장은 실패가 발생하기 위해 반드시 참이어야 하는 정확한 조건을 번호가 매겨진 조건으로 나열하십시오 ("1. 연산이 범위 종료 후 다른 서비스를 호출하고, 2. 해당 호출 주변에 새 범위가 열리지 않는다"). 그런 다음 무엇이 잘못될지(어설트, 예외 유형, 줄)를 명명하십시오. 아무도 보지 못한 오류 메시지를 인용하지 마십시오. 예외를 명명하는 경우 코드를 읽은 것에서 비롯되었다고 말하십시오.
• "증상이 이렇게 보이는 이유"를 "오늘 아무도 이것을 맞지 않는 이유"로 대체하십시오. 각 실제 호출자 또는 흐름을 살펴보고 충족하지 못하는 조건을 링크와 함께 보여주십시오. 이 섹션이 이야기의 무게를 지탱합니다. 독자는 리스크가 살아있는지 결정해야 하기 때문입니다.
• 확인하지 않은 호출자를 찾으십시오. 리스크에 대한 "문제가 얼마나 심각한지" 목록을 작성하는 것은 확인되지 않은 경로가 나타나는 곳입니다: 일반적인 장소 외부에서 이루어진 호출, 다른 전송, 백그라운드 작업. 각각을 생략하지 말고 확인되지 않은 것으로 나열하고 어떤 증거가 있는지(예: 추적 없이 실행한 깨끗한 테스트 실행) 말하십시오.
• 수정 섹션에서 비용을 비교하십시오. 리스크에 대한 수정은 실제 실패를 다시 불러올 수 있습니다. 그렇다면 그것을 명확히 말하십시오: 수정은 아무도 맞지 않는 리스크를 발생하는 실패와 교환합니다.

지금 시작된 이유 (Why it started now)

동작이 회귀인 경우 무엇이, 언제 변경되었고, 그 변경이 그 자체로는 왜 합리적이었는지 말하십시오. PR 또는 커밋을 먼저 단어로 명명하고 괄호 안에 ID를 넣으십시오. 독자는 이전 변경이 부주의한 것이 아니라 불완전했을 뿐임을 알아야 합니다.

문제가 얼마나 심각한지 (How bad it is)

실제 영향을 나열하십시오: 데이터, 숫자, 알림, 로그 노이즈. 확인된 것과 추론된 것을 분리하십시오. 독자는 이러한 주장을 다른 사람에게 반복할 것이기 때문입니다.

• 각 주장을 확인됨(그리고 어떻게: 테스트, 로그 쿼리, 종단 간 코드 경로 읽기) 또는 확인되지 않음으로 표시하십시오.
• 무언가 검증하지 않았다면 "데이터는 괜찮다"고 쓰지 마십시오. 그럴듯한 주장이 틀린 것으로 판명되면 솔직한 "아직 확인되지 않음"보다 더 많은 신뢰를 잃습니다.

수정 방법 (How to fix it)

가장 작은 것부터 가장 큰 것(예: 빠른 수정 및 적절한 수정)까지 옵션을 제시하고, 각각이 이야기 측면에서 무엇을 변경하는지("두 등장인물 모두에게 동일한 달력을 제공"), 그리고 그 한계를 설명하십시오. 짧은 권장 사항으로 끝내십시오.

스타일 (Style)

• 평범한 단어를 사용하십시오. 모든 용어를 처음 나타날 때 정의하거나 생략하십시오.
• 코드 식별자를 비유 옆에 백틱 안에 유지하여 이야기가 코드로 추적 가능하게 하십시오.
• 긴 블록보다는 짧은 단락과 글머리 기호를 선호하십시오.
• 사용자의 CLAUDE.md 또는 AGENTS.md 파일에 있는 작성 스타일 규칙을 따르십시오.

이야기 후 (After the story)

등장인물에 대한 후속 질문("그럼 X가 핸들러인가요?")을 예상하십시오. 등장인물을 정확한 코드에 고정하여 답변하십시오: 실행되는 항목을 file:line 링크와 함께 순서대로 나열하고, 중요한 일을 하는 부분이 무엇인지 말하십시오. 질문이 원래 이야기에서 등장인물을 느슨하게 명명했음을 보여주면 방어하지 말고 답변에서 명명을 수정하십시오.

예시 (Example)

references/example-stale-prices.md에는 오래된 캐시 버그에 대한 전체 이야기가 이 스타일로 작성되어 있으며, 무엇이 잘못되었는지에 대한 노트도 포함되어 있습니다. 세션에서 첫 번째 이야기를 작성하기 전에 길이와 톤을 보정하기 위해 읽어보십시오.