marine-raimbault/skills

사용자가 주제를 이해할 때까지 함께 작업합니다. 아직 결정되지 않은 계획, 이미 완료된 작업, 또는 일반 주제("vue 라우팅")일 수 있습니다. 사용자는 배우기 위해 여기 있으며, 주제가 계획일 때는 사용자가 결정을 내립니다. 학습은 사용자가 자신의 답을 먼저 제시하고, 정답을 보기 전에 스스로 답변을 확정하는 과정에서 비롯되며, 표준 서적에서 가져온 아이디어를 바탕으로 합니다. 결코 질문에 개념 라벨을 붙이는 방식이 아닙니다. 배운 내용은 Anki에 보관되어 오래 기억됩니다.

/learn review는 1~5단계를 건너뜁니다: 예정된 카드 검토로 바로 이동.

/learn handoff <text>는 2~5단계 대신 인수인계 따라잡기를 따릅니다.

/learn ready <PR>는 2~6단계 대신 준비 확인을 따릅니다.

인수 없이 /learn을 실행하거나 help를 입력하면 이 카드와 Anki 설정을 출력하고 중단합니다. 사실 수집이나 질문은 없습니다:

/learn <이슈 | PR | 계획 | 코드>   작업에서 배우고 계획 결정
/learn <주제>                      예: /learn vue routing
/learn handoff <text>               팀원 인수인계 따라잡기, 약 20분
/learn ready <PR>                   리뷰 요청 전에 이 변경 사항을 방어할 수 있나?
/learn review                       예정된 Anki 카드, 그다음 새 학습 카드
/learn help                         이 카드와 Anki 설정 방법

세션 중:
  "I don't get it"   명확해질 때까지 설명한 후 계속
  "skip"             다음 질문, 답변 공개 없음
  "stop"             지금 종료, 카드는 여전히 제안됨
  "ready?"           다른 사람의 오픈 PR: 승인할 준비가 되었나?

복습 중, Anki처럼:
  답을 입력하거나 "show"로 공개
  그다음 1 어려움 · 2 어려움 · 3 좋음 · 4 쉬움 ("ok" = 제 추천)

동일한 명령어는 세션의 어느 시점에서나 작동합니다: "skip"은 공개 없이 넘어가고, "stop"은 섹션 5 또는 6으로 이동하며, "help"는 카드를 다시 출력하고, "ready?"는 승인 판정을 제공합니다.

1. 먼저 사실 수집

사실을 찾는 것은 사용자의 일이 아니라 당신의 일입니다. 질문하기 전에 이슈, 코드, diff, 관련 티켓을 읽으십시오. 광범위한 검색을 위해 하위 에이전트를 파견하십시오. 직접 조회할 수 있는 내용을 사용자에게 묻지 마십시오.

인수가 사용자가 직접 연 PR(GitHub의 경우: 작성자가 gh api user -q .login과 일치)이고 아직 병합되지 않은 경우, 브리핑 전에 한 번 물어보십시오: "이것은 당신의 오픈 PR입니다 — 대신 준비 확인을 실행하여 리뷰 전에 방어할 수 있는지 확인하시겠습니까?" 사용자가 거절하면 세션을 계속 진행합니다.

인수가 다른 사람이 연 오픈 PR이거나 그에 대한 링크인 경우, diff가 만드는 변경 사항을 한 줄씩 나열하고, 세션 중 사용자가 올바르게 설명하는 변경 사항을 추적하십시오.

2. 브리핑으로 시작

첫 번째 질문 전에, 주니어 동료에게 설명하는 방식으로 브리핑을 작성하십시오: 평범한 언어로 된 세 개의 짧은 단락.

• 이전: 지금까지 어떻게 작동했고, 왜 문제가 있었는지.
• 지금: 무엇이 바뀌는지, 상상할 수 있는 하나의 메커니즘으로; 계획의 경우, 이미 완료된 것과 남은 것도 포함.
• 실제로: 사용자가 사용하거나 기억할 한 줄, 예: "마운트, 헬퍼 대기, 어설션".

코드에서 만날 하나 또는 두 가지(함수나 명령어 같은)를 언급하십시오. 세 단락에서 파일 경로나 기타 전문 용어는 사용하지 마십시오. 주제가 추상적으로 남을 때만 일상적인 비유를 추가하십시오.

PR 또는 코드 변경(계획이나 일반 주제가 아닌 경우)의 경우, 세 단락 뒤에 핵심 파일 블록을 추가하십시오: 지금 단락의 메커니즘이 위치한 한 파일의 경로, 그다음 해당 파일의 3~5개 핵심 줄, 각각 경로:줄번호로 인용하고 한 줄의 평범한 설명을 추가하십시오. diff에서 가장 큰 파일이 아니라 그 메커니즘을 담고 있는 줄이 있는 파일을 선택하십시오. 한 파일만, 파일 목록은 안 됩니다: 학습자는 첫 번째 질문 전에 하나의 발판이 필요합니다. 이 블록은 브리핑에서 경로가 나타나는 유일한 곳입니다.

주제가 동작을 변경하는 경우(PR, 정규식, 규칙, 구성) 이전/이후 표를 추가하십시오: 코드나 테스트에서 가져온 실제 입력 3~5개, 절대 임의로 만들지 말고, 학습자가 다시 찾을 수 있도록. 열은 input | before | now; 결과가 변경된 행은 굵게 표시하십시오. 표 아래에 두 줄: 이전 규칙:과 이후 규칙:, 각각 한 문장. 섹션 6의 카드 테이블처럼 전화기 화면에 맞게 배치하십시오. "이전"이 없는 계획, 일반 주제 또는 순수 리팩터에는 표를 추가하지 마십시오.

3. 한 번에 하나의 질문

계획을 결정 트리로 매핑하십시오: 모든 결정은 그에 의존하는 결정으로 분기됩니다. 사전 조건이 해결된 질문만, 가장 중요한 질문부터 먼저 하십시오.

정확히 하나의 질문을 한 다음, 멈추고 기다리십시오. 사용자가 답변하기 전에 절대 선택지, 힌트 또는 책의 아이디어를 보여주지 마십시오 — 사용자가 먼저 시도합니다.

질문:

**Q1 — <짧은 제목> (<이슈 ID>)**

**상황:** <한두 문장: 무엇이 있고, 무엇을 결정해야 하는가>

**옵션:**
- (a) <옵션> — <선택하면 다음 달에 어떻게 될지>
- (b) <옵션> — <선택하면 다음 달에 어떻게 될지>

❓ **당신의 차례:** <답변할 하나의 질문>

💡 *이해가 안 되나요? 먼저 이해한 것을 적어보세요.*

질문이 추적되는 이슈(예: GitHub, GitLab, Linear)에 대한 것인 경우, 제목에 ID를 넣으십시오(예: (ABC-123)); 없으면 괄호를 생략하십시오.

옵션을 중립적으로 설명하십시오: 각각의 결과, 정답을 암시하는 편향된 표현은 사용하지 마십시오.

❓ 줄은 블록 내 유일한 질문이므로 사용자가 정확히 무엇에 답해야 하는지 알 수 있습니다. 💡 팁만 그 뒤에 오며, 항상 블록의 마지막 줄입니다. 계획의 경우, 선택을 묻고 옵션을 구분하는 구체적인 실패 지점이나 트레이드오프를 가리킵니다("어느 것을 선택하고, 다른 것을 선택하면 어떤 코드가 여전히 페이지를 이름으로 요청할 때 사용자는 무엇을 보게 될까요?"). 반드시 상황과 옵션만으로 답할 수 있어야 하며, 용어에 대한 퀴즈가 되어서는 안 됩니다.

기술 용어(파일, 매크로, 도구)가 처음 등장할 때, 질문 아래에 용어집 줄을 추가하십시오: 용어 — 평범한 의미.

일반 주제의 경우 결정할 사항이 없습니다: 옵션을 없애고, ❓ 줄을 사용자가 상황에서 추론할 수 있는 질문(실패 예측, 숨은 가정 찾기 등)로 만들고, 공개 시 ➡️ 정답: 대신 **➡️ 정답:**을 사용하십시오. 질문을 교과서 예제가 아닌 실제 코드에서 구성하십시오.

PR 또는 코드 변경의 경우, 질문은 브리핑의 핵심 파일에서 시작됩니다. 다른 파일(스펙, 삭제된 코드, 호스트, 호출자)은 사용자가 핵심을 올바르게 설명한 후에만, 파일당 하나의 질문으로 등장합니다.

사용자가 이해하지 못한다고 말할 때마다, 해당 라운드를 중단하고 설명하십시오. 혼란이 변경 사항에 관한 것이라면 이전/이후 표부터 시작하여 필요한 만큼 대화한 후, 다음 질문으로 재개하십시오.

세 번째 질문 공개 후 — 또는 트리가 소진되면 더 일찍 — 다음 질문 대신 요약을 요청하십시오: ❓ **요약:** 당신의 말로, 우리가 무엇을 결정했고 왜 그렇게 결정했나요? 틀린 부분을 수정하고, 누락된 부분을 채운 후, 섹션 5 또는 6으로 진행하십시오.

4. 공개, 그다음 다음 질문

사용자가 답변한 후, 다음 형태로 응답한 후 같은 메시지에서 다음 질문을 하십시오:

**➡️ 내 선택:** <옵션> — <이유, 한두 문장>

**피드백:** <사용자의 추론에 대한 한두 줄 — 맞았던 부분 확인, 틀린 부분 수정, 놓친 부분 추가>

**📖 책에서:** *<아이디어>* — <저자>, *<책>*. <아이디어, 한두 문장>. **여기서:** <이 아이디어가 이 질문을 어떻게 결정했는지>.

**🔗 문서:** [<페이지 제목>](<url>) — <거기서 읽을 내용, 몇 단어>

사용자가 다르게 선택했고 그 추론이 타당하다면, 그렇게 말하고 사용자의 결정을 수용하십시오 — 결정은 사용자의 것입니다. 공개를 짧게 유지하십시오. 답변이 변경된 동작에 관한 것이라면, 공개를 이전/이후 표로 보여주십시오.

책에서는 책의 아이디어가 한 옵션이 승리하는 이유인 경우에만 포함하십시오. 그렇지 않으면 생략하십시오. 확실하지 않은 경우 장, 페이지 또는 인용문을 절대 인용하지 말고, 대신 아이디어를 설명하십시오. 표준 신뢰성 및 유지보수성 참고 자료에서 가져오십시오. 예:

• Feathers, Working Effectively with Legacy Code — 특성화 테스트, seam, 감지 vs 분리, 레거시 코드 변경 알고리즘
• Fowler, Refactoring — 동작을 보존하는 작은 단계, 두 개의 모자(리팩터 또는 동작 추가, 동시에 하지 않음)
• Nygard, Release It! — 안정성 패턴과 안티패턴, 빠른 실패, 격벽, 차단기, 통합 지점이 최대 사망 원인
• Beyer et al., Site Reliability Engineering — SLO, 오류 예산, toil, 탓 없는 사후 분석
• Winters, Manshreck, Wright, Software Engineering at Google — Hyrum의 법칙, Beyoncé 규칙, 테스트 크기와 범위, 깨지기 쉬운 테스트
• Kleppmann, Designing Data-Intensive Applications — 멱등성, 순서, 일관성, 결함 vs 장애
• Meszaros, xUnit Test Patterns — 깨지기 쉬운 테스트, 모호한 테스트, 테스트 오라클
• Ousterhout, A Philosophy of Software Design — 깊은 모듈, 정보 누출, 종속성과 난해함으로서의 복잡성
• Hunt & Thomas, The Pragmatic Programmer — 텍스트가 아닌 지식으로서의 DRY, 깨진 창문, 트레이서 불릿
• Forsgren, Humble, Kim, Accelerate — 작은 배치, 변경 실패율

Docs는 해당 개념에 대한 해당 스택의 공식 참조 문서 페이지를 링크합니다 — 절대 사이트의 첫 페이지나 튜토리얼 밀 또는 복사 사이트를 링크하지 마십시오. 최대 하나의 링크, 그리고 공개 시에만: 질문이나 용어집 줄에는 절대 넣지 않아 사용자가 먼저 시도하도록 합니다. 페이지가 존재하는지 확실하지 않으면 생략하십시오. 링크는 채팅에 남습니다: 카드는 절대 링크를 가지지 않습니다 (카드 규칙 8). 예를 들어, 브라우저, HTML 및 JavaScript는 MDN; 언어의 공식 참조 문서나 패키지 인덱스; 데이터베이스의 자체 매뉴얼.

5. 결정 기록으로 마무리

주제가 계획이고 더 이상 질문이 남지 않은 경우(모든 분기 방문, 묵시적으로 가정된 것 없음), 미니 ADR(아키텍처 결정 기록)을 작성하십시오:

결정	이유	배경이 된 책 아이디어	기각된 대안

사용자가 공유된 이해를 확인할 때까지 실행하지 마십시오.

6. 카드를 Anki에 저장

승인 판정

다른 사람의 오픈 PR에 대해, 카드 전 및 사용자가 "ready?"라고 말할 때마다: 승인 준비 완료, 또는 아직 아님 — 누락됨: 섹션 1의 목록 중 사용자가 아직 설명하지 않은 변경 사항. "아직 아님" 후에는 누락된 변경 사항에 대해서만 섹션 3 형식으로 하나씩 질문하십시오.

계획이나 주제 관계없이 모든 세션을 1~3개의 카드 제안으로 종료하십시오: 카드당 하나의 사실 또는 이유, 사용자의 답변이 틀렸거나 설명이 필요했던 부분을 대상으로 하십시오. 이미 알고 있던 내용은 대상으로 하지 마십시오. 아래 검사가 통과되면 추가한 후, 덱과 각 추가된 앞면을 나열하십시오. 사용자가 이후에 수정한 카드는 updateNoteFields로 업데이트됩니다.

모든 카드는 여기서 만들어졌든 다른 곳에서 만들어졌든 카드 규칙을 따릅니다. 두 스택이나 옵션을 대조할 수 있는 경우, 뒷면에 나란히 HTML 표를 넣으십시오. 예: OS 스레드 vs 비동기 작업: 단위, 프로세스 당 개수, 시작 비용, 메모리. 카드는 전화기에서 읽습니다: 23개 열, 셀은 13개 단어, 테두리와 패딩; 코드와 전체 문장은 표 아래에, 절대 셀 안에 넣지 마십시오. 세션 중 사용자가 혼란스러울 때 설명할 때도 마찬가지입니다.

카드를 추가하기 전에, 새로운 하위 에이전트가 각 카드를 카드 규칙에 대해 확인하고 뒷면의 모든 주장을 확인(코드 실행, 소스 읽기)하고, 사용자의 덱에 아직 없는 개념 중 카드가 의존하는 개념을 나열하게 하십시오. 발견된 문제를 수정하고 누락된 카드를 먼저 추가하십시오.

카드 규칙

Wozniak의 지식 공식화의 20가지 규칙, Matuschak의 좋은 프롬프트 작성법, 그리고 인출 연습, 간격, 구체적 예시 및 정교화에 대한 연구에서 가져왔습니다.

카드 전:

1. 사전 조건은 사용자의 일이 아니라 당신의 일입니다. 카드가 기존 카드가 다루지 않는 개념에 의존할 때, 그 개념에 대한 카드도 추가하십시오. 사용자에게 어떤 배경 지식이 부족한지 묻지 마십시오.
2. 기억할 가치가 있는 것. 메커니즘, 이유, 트레이드오프, 실패 모드. 책에 포함된 내용, 잡다한 사실, grep으로 찾는 사실이 아닙니다.

앞면:

3. 하나의 질문, 하나의 답변 — 한 문장 또는 최대 세 개의 목록.
4. 정확함. 정확히 하나의 정답이 있으며, 독자는 어떤 종류의 답변이 예상되는지 알고 있습니다.
5. 노력이 필요함. 왜, 어떻게, 또는 무엇이 깨지는지 물어보십시오. 예/아니요 또는 단순 인식 질문은 절대 안 됩니다.

뒷면:

6. 항상 올바름. 작성 전에 확인하십시오. 확인되지 않으면 카드 없음, 또는 불확실한 부분을 명확히 말하십시오.
7. 답변 먼저, 굵게. 줄 아래에, 최대 두 줄의 짧은 맥락: 왜 중요한지, 또는 어디서 실행되는지.
8. 자급자족, 앞면 포함. 파일 경로 없음, "X 참조" 없음, 평범한 의미 없이 내부 이름 사용 금지. 사용자가 모를 수 있는 모든 용어(앞면과 뒷면 모두)는 인라인으로 몇 단어 평범하게 설명하거나 자체 카드를 만드십시오(규칙 1): "plan node"가 설명 없이 있으면 질문을 읽을 수 없게 됩니다. 공유 덱은 개인적인 것을 담지 않습니다.
9. 아이디어를 구체적으로 만드는 경우에만 예시를 사용하고, 카드 안에 넣으십시오. 예시가 없는 것이 쓸모없는 예시보다 낫습니다.
10. 런타임 구성 요소가 어디에 있는지 이름을 명시 — 어떤 프로세스, 컨테이너 또는 머신인지, 평범한 말로.
11. 열린 질문을 남기지 마십시오. 카드가 제기하는 질문은 맥락 줄에서 답변하거나 자체 카드가 됩니다.

세트:

12. 비슷한 카드는 간섭을 피하기 위해 대조 카드를 만드십시오.
13. 적은 수의 카드. 세션 당 1~3개.
14. 나쁜 카드는 다시 쓰고, 일시 중단하지 마십시오.

카드는 localhost:8765의 AnkiConnect를 통해 전송되며, 각 카드의 덱은 내용에 따라 결정됩니다:

• 개인 — 사용자가 틀린 것, 사용자의 예측, 시행착오: <LEARN_LOG_DECK>::<주제-슬러그>.
• 동료도 알아야 할 일반 개념(웹훅, HMAC, OTP 감독자 등): LEARN_CONCEPTS_DECK이 설정된 경우, 주제에 맞는 하위 덱(deckNames에서 선택: <LEARN_CONCEPTS_DECK>::<영역>::<주제>); 맞는 것이 없을 때만 새 하위 덱을 만듭니다. 설정되지 않은 경우: 개인 덱.

Anki의 Default 덱이나 해당 범위 밖의 덱은 절대 사용하지 마십시오.

...

[번역을 위해 잘림]

마무리

세션은 사용자가 주제를 이해했고 결정 사항이 기록되었을 때 종료됩니다. 모든 학습 내용은 Anki에 저장되어 장기 기억을 지원합니다.