여기서 설명이란 사용자의 언어로 된 인과 관계 사슬입니다: 각 주장이 이유를 포함한 짧은 몇 문장으로, 사용자가 이미 다루는 용어로 구성되며, 한 번에 읽을 수 있고 필요하면 소리 내어 읽을 수 있어야 합니다.
1. 사용자의 언어 수집
설명은 사용자가 알고 있는 것, 그리고 사용자가 입력한 단어에 드러난 것에 기반합니다. 세션에서 처음으로 주제를 설명하기 전에, 사용자가 해당 주제에 대해 어떻게 이야기해 왔는지 확인하세요:
python3 <이 스킬 폴더>/user_words.py <키워드> [<키워드> ...]
python3 <이 스킬 폴더>/user_words.py --all-projects <키워드> ...
이 명령어는 현재 프로젝트 또는 모든 프로젝트에서 사용자가 이전 Claude 세션에서 입력한 메시지 중 키워드를 포함한 것을 최신순으로 출력합니다. 사용자의 질문과 주제(컴포넌트 이름, 도구, 실패한 것)에서 키워드를 선택하세요. 현재 대화의 사용자 메시지도 추가하세요.
이를 통해 다음 세 가지를 파악하세요:
- 사용자의 용어: 각 사물을 지칭하는 사용자의 단어("zweiter SSH-Weg", "incoming IP", "proxied"). 코드나 문서에서 다르게 명명되더라도 이것들을 정확히 사용하세요.
- 알려진 기반(known ground): 사용자가 진술했거나 올바르게 사용한 내용. 사슬은 여기서 끝날 수 있습니다.
- 격차(gaps): 주제에서 사용된 용어 중 사용자가 한 번도 사용하지 않은 것. 각각은 새로운 단어입니다.
설명에 필요한 모든 용어가 사용자의 용어 또는 새로운 단어로 분류될 때까지 완료되지 않습니다.
2. 사슬 작성하기
- 문제부터 먼저. 첫 문장은 문제나 답변 자체를 명명합니다: "문제는 X입니다." 사용자가 직접적인 질문을 한 경우("왜 그 비밀번호가 필요한가요?"), 첫 문장은 정확히 그 질문에 답합니다.
- 모든 주장은 이유를 포함합니다. 같은 문장에서 weil / da / durch로 이유를 붙이세요. 단독으로 언급된 결과는 열린 연결 고리입니다: "모든 연결이 127.0.0.1에서 온다"는 "fail2ban이 IP별로 차단한다"가 옆에 올 때까지 아무것도 설명하지 않습니다.
- 알려진 기반까지 연결. 마지막 이유가 알려진 기반이 될 때까지 이유를 따라가세요. 거기서 멈추세요.
- 사용자의 용어, 메커니즘 그 자체. 실제 메커니즘을 사용자의 용어로 그대로 기술하세요. 비유, 이미지, 지어낸 표현은 사용하지 마세요.
- 새로운 단어는 괄호 안에. 새로운 단어는 처음 한 번만 바로 뒤에 키워드를 괄호 안에 넣어서 사용하고, 그 후에는 괄호 없이 사용합니다: "HostKeyAlias (SSH 옵션: known_hosts의 다른 항목에 대해 호스트 키를 확인)". 키워드, 문장이 아닙니다.
- 말하듯이 산문체. 3~5개의 짧은 평서문, 각 문장에 하나의 연결 고리, 원인에서 결과 순서로. 텍스트-음성 변환을 견딜 수 있는 평이한 흐름의 텍스트: 설명 내부에 제목, 표, 글머리 기호 목록을 사용하지 마세요.
아키텍처의 경우 사슬은 하나의 요청 또는 하나의 변경 경로를 따라갑니다: 어떤 부분이 작용하고, 무엇을 다음에 전달하며, 왜 다음이 그것으로 자신의 작업을 수행하거나 수행할 수 없는지.
3. 수정 사항 명명
사용자의 표현과 가정은 코드와 사실에 대해 확인되며, 모든 편차는 사슬 뒤에 한 줄씩 "당신은 … 라고 말합니다 / 올바른 것은 … 입니다, 왜냐하면 …" 형태로 명명됩니다:
- 코드가 지원하지 않는 표현: 사용자가 "Passkey"라고 말하지만 실제로는 키체인 항목입니다. 사용자가 "Runner가 다운됐다"고 말하지만 Runner는 컨테이너이고 Docker가 실패한 것입니다. 코드나 도구가 사용하는 이름을 제공하여 사용자의 다음 질문과 검색 결과가 정확하도록 하세요.
- 잘못된 가정: 사용자가 당연하게 여기지만 사실이 아닌 것("연결을 위해 그 비밀번호가 필요합니다"). 실제로 해당하는 사항과 그 이유를 말하세요.
수정하기 전에 코드나 시스템에 대해 확인하세요. 기억에 의존한 수정은 추측입니다. 이후에는 사용자의 용어가 올바른 경우에만 계속 사용하세요.
모델
사용자가 받았어야 할 설명의 사용자 자신의 표현 (fail2ban이 Cloudflare 터널 뒤에서 SSH를 보호하지 못하는 이유). 여기의 예제는 독일어입니다. 사용자가 작성하는 언어로 설명하세요.
문제는 비밀번호를 사용한 두 번째 SSH 경로입니다. Mac의 사용자 이름과 사용자 비밀번호를 사용하면 누구나 무차별 대입 공격(Brute Force)으로 연결을 설정할 수 있습니다. fail2ban은 보호하지 않습니다. 왜냐하면 그것은 IP 기반 차단이며, 터널을 통해 모든 사람이 동일한 수신 IP를 가지기 때문입니다. Cloudflare가 프록시(proxied)하기 때문입니다.
완료 조건
보내기 전에 각 문장을 확인하세요:
- 첫 문장이 문제를 명명하거나 질문한 질문에 답합니까?
- 모든 주장이 같은 문장에 이유를 포함합니까?
- 마지막 이유가 이 사용자에게 알려진 기반입니까?
- 모든 용어가 사용자의 용어이거나, 괄호가 있는 새로운 단어입니까?
- 사용자 질문의 모든 잘못된 표현과 잘못된 가정이 그 수정 사항과 함께 명명되었습니까?
사용자가 여전히 이해하지 못하면, 이유가 누락된 하나의 연결 고리를 찾아서 그 연결 고리만 한 문장으로 제공하세요. 구체적인 값(두 개의 IP, 하나의 요청)은 그 연결 고리를 닫기 위해 그곳에만 사용합니다.
다음에 해야 할 일(옵션, 명령어, 권장 사항)은 설명 뒤에, 설명과 분리되어, 요청되거나 행동에 필요할 때만 옵니다.