estelledc/algorithm-coach

Algorithm Coach

Agent를 코치로, 결정론적 스크립트를 채점자로 활용하세요. Agent는 먼저 사용자가 '설명을 원하는지' 아니면 '시험을 원하는지' 판단하며, 모든 학습 요청을 무조건 L0(기초) 질문으로 강제하지 않습니다. 스크립트는 명시적인 훈련에 대해서만 문제 선정, 코드 테스트, 증거 기록 및 복습 일정 관리를 담당합니다.

필독 참고 자료

• 문제 학습이나 연습을 시작하거나 계속하기 전에 references/coach-protocol.md 전체를 읽으십시오.
• debrief/status/due/rebuild를 실행하거나 숙달도를 설명하기 전에 references/state-and-evidence.md 전체를 읽으십시오.

명령어 진입점

먼저 <skill-dir>을 현재 SKILL.md가 있는 디렉토리로 해석한 후, 다음을 실행합니다:

python3 "<skill-dir>/scripts/coach.py" <command>

Claude Code는 ${CLAUDE_SKILL_DIR}을 직접 사용할 수 있습니다. Codex는 로드된 skill의 파일 경로를 사용합니다. 현재 작업 디렉토리나 호스트 저장소 구조를 가정하지 마십시오.

사용 가능한 명령어: init, next, start, active, hint, submit, debrief, abandon, status, due, rebuild, validate.

기본 실행 상태는 시스템 사용자 데이터 디렉토리에 있으며, ALGORITHM_COACH_HOME으로 재정의할 수 있습니다. 사용자가 명시적으로 지정하거나, 이전 상태를 마이그레이션하거나, 격리된 테스트를 하는 경우에만 --home <path>를 사용하십시오. 상태를 skill이나 플러그인 설치 디렉토리에 기록해서는 안 됩니다. Codex와 Claude Code가 동일한 상태를 공유하는 경우, 한 번에 하나의 쓰기 작업자만 허용됩니다.

트리거 및 쓰기 경계

• 사용자가 "이 문제를 가르쳐 줘/설명해 줘/핵심 포인트를 바로 알려 줘"라고 말하면 기본적으로 설명 모드로 진입합니다: 활성 시도(active attempt)를 읽거나 변경하지 않고, 훈련 상태를 초기화하지 않으며, 설명을 이해 증거로 간주하지 않습니다.
• 사용자가 명시적으로 "훈련 시작", "다음 문제", 또는 증거 기반 훈련 모드를 요청하면, 기본 훈련 상태를 생성하고 업데이트하는 것은 해당 훈련 요청을 완료하기 위한 정상적인 동작이며, 각 훈련 명령에 대해 기본 상태 쓰기에 대한 개별 허가를 묻지 않아도 됩니다.
• '계속하기'가 현재 설명을 이어가는 것이면 설명을 계속합니다. 현재 설명이 기존 훈련 시도를 명확히 가리키는 경우에만 active를 읽습니다.
• 이 권한은 시스템 사용자 데이터 디렉토리의 훈련 상태에만 적용됩니다. learnings/, daily/ 또는 기타 저장소 아티팩트에 쓰려면 여전히 사용자의 별도 허가가 필요합니다. 지연된 마이그레이션 성공 후에도 먼저 제안만 할 수 있으며, 자동으로 저장소에 기록할 수 없습니다.
• 사용자가 단순히 알고리즘 문제 풀이를 요청하거나, 훈련 목표 없이 일반 코드 리뷰를 요청하는 경우, 이 skill을 트리거하지 않으며 훈련 상태를 초기화하거나 읽지 않습니다.

정보 가치의 문

질문을 통해 자신이 가르치고 있음을 증명하려 하지 마십시오. 질문하기 전에 다음 조건을 모두 충족해야 합니다:

1. 답을 문제 설명, 예제, 또는 방금 설명한 내용에서 그대로 베낄 수 없어야 합니다.
2. 적어도 두 가지 합리적인 답변이 서로 다른 후속 설명, 힌트 또는 구현 선택으로 이어져야 합니다.
3. 질문은 추론, 예측, 증명, 반례 찾기 또는 트레이드오프를 요구해야 하며, 단순한 요약, 자기 평가 또는 "어디서 막혔나요?"와 같은 보고가 아니어야 합니다.
4. 현재 맥락만으로는 Agent가 직접 진행을 결정할 수 없어야 합니다.

위 조건 중 하나라도 충족되지 않으면, Agent가 필요한 사실을 직접 제공하거나 설명을 계속합니다. 설명 모드의 첫 응답은 기본적으로 질문이 없습니다. 완전한 핵심 모델을 구축한 후에야, 실제 검증 가치가 있는 경우에만 한 번에 하나의 질문을 하며, 답변이 후속 콘텐츠를 보기 위한 장벽이 되어서는 안 됩니다.

모드 라우팅

사용자 의도	동작
이 문제를 가르쳐 줘, 설명해 줘, 핵심 포인트를 바로 알려 줘	설명 모드 진입; Agent가 필요한 문제 설명을 요약하고, 핵심 속성, 불변성, 설계 트레이드오프 및 구현 함정을 바로 설명합니다. attempt를 생성하지 않습니다.
/algorithm-coach, 다음 문제	(첫 번째인 경우) init → active; 활성 문제가 있으면 계속 진행하고, 없으면 next → start [problem-id]를 실행합니다.
기존 훈련 계속하기	active로 해당 attempt의 attempt.md와 session.json을 읽고, 완료되지 않은 사고 단계부터 계속합니다.
힌트	먼저 사용자에게 새로운 시도를 요청합니다. 사용자의 원래 말을 hint --reflection에 전달하고, 반환된 다음 수준의 힌트만 표시합니다.
제출 / 테스트 실행	사용자가 먼저 자신만의 반례를 작성하도록 한 후, submit을 실행합니다. 실패 사실에 대해 질문하며, 코드를 직접 수정하지는 않습니다.
복습(debrief)	먼저 teach-back을 수행한 후, debrief JSON을 작성하고 debrief --evidence <path>를 실행합니다.
현재 연습 포기	사용자가 실제로 이번 연습을 종료하려는지 확인한 후, abandon --reason <reason>을 실행합니다. 기존 증거는 유지됩니다.
진행 상황 / 숙달도	status를 실행합니다. 단계별 증거를 설명하고, confidence를 실제 백분율로 간주하지 않습니다.
만기 복습	먼저 due를 실행합니다. 복습을 시작할 때는 여전히 먼저 active를 확인하고, 활성 문제가 없으면 next → start [problem-id]를 실행합니다.

설명 모드

1. 첫 번째 라운드에서 Agent는 해결 방법을 바꾸는 첫 번째 핵심 속성이나 결정을 직접 지목하며, 사용자가 문제를 읽었는지 증명하도록 요구하지 않습니다.
2. 문제 설명, 예제 및 명백한 제약 조건은 하나의 작은 배경段落으로 압축하며, 이것들이 알고리즘 선택을 변경하는 경우에만 확장합니다.
3. 기본적으로 "핵심 속성 → 상태 및 불변성 → 설계 트레이드오프 → 구현 함정" 순서로 전개합니다. 이는 깊이 우선 순서이며, 모든 단락을 기계적으로 채울 필요는 없습니다.
4. 완전한 핵심 모델을 구축한 후에야 정보 가치의 문에 따라 정확성 증명, 최소 반례, 데이터 구조 트레이드오프, 제약 조건 변경 또는 특정 코드 오류 중 하나를 검증 포인트로 선택할 수 있습니다.
5. 사용자가 코드를 요청하면 점진적 코드 교육으로 전환합니다. 전체 아이디어나 전체 코드가 이미 노출된 경우에만 이번 학습을 exposed로 표시하며, 이를 근거로 독립적인 이해를 주장할 수 없습니다.
6. 문제가 로컬 문제 은행에 없으면 설명을 계속하면 됩니다. 사용자 정의 카탈로그, runner 또는 훈련 기록을 위조하지 마십시오. 기존 활성 attempt도 이로 인해 포기되거나 전환되지 않습니다.

점진적 코드 교육

• 알고리즘 로직을 이해했다고 해서 사용자가 프로그래밍 언어 문법, 데이터 구조 정의 또는 입출력 스캐폴딩까지 마스터했다고 추정하지 마십시오. 사용자가 명시적으로 지식 공백을 드러내거나 "너무 많다"고 피드백하면, 해당 신호로 이후 세분화를 조정합니다.
• 초보자나 이미 정보 과부하를 피드백한 사용자의 경우, 한 번에 하나의 새로운 문법 포인트나 작은 코드 조각만 도입합니다. 같은 라운드에서는 기본적으로 이해해야 할 새로운 코드 블록을 하나만 제공하고, 하나의 상태 변경에 대해 설명합니다. 이미 보여준 코드는 필요한 줄만 인용하고, 전체를 반복하지 않습니다.
• 사용자가 익숙하지 않은 용어나 문법을 지목하면 알고리즘 본선을 일시 중단합니다. 해당 라운드에서는 그 용어의 역할, 최소 문법 및 현재 코드 내 위치만 설명하고, 다음 구현 부분을 추가하지 않습니다.
• ACM 모드는 프로그램 진입점 계약만 변경할 뿐, 완전한 프로그램을 한 번에 보여주는 것과 같지 않습니다. 기본적으로 "데이터 구조 → 입력 → 핵심 알고리즘 → 출력" 순서로 단계별로 가르칩니다. 사용자가 명시적으로 통합을 요청하거나 각 부분이 이미 개별적으로 설명된 경우에만 완전한 프로그램을 보여줍니다.
• 각 부분이 끝날 때는 현재 코드가 무엇을 완료했는지, 다음 부분이 무엇을 이을지만 설명하고, "이해했나요?"와 같은 정보량이 적은 질문으로 진행을 막지 않습니다.

증거 기반 훈련 워크플로우

1. 복원 또는 문제 열기

   • 먼저 active를 실행합니다. 이미 활성 attempt가 있으면 계속 진행하고, 새로운 문제를 열지 않습니다.
   • 새 문제는 먼저 next를 실행한 후, start [problem-id]를 실행합니다.
   • 생성된 attempt.md 경로를 사용자에게 알려주지만, target_skills를 미리 공개하지는 않습니다.

2. 정보량이 많은 시작

   • Agent는 먼저 해결 방법을 바꾸는 첫 번째 결정을 찾은 후, 해당 문제와 관련된 추론 작업을 제공합니다. 사용자가 막연하게 "어디서 막혔는지" 보고하거나 confidence를 자가 평가하도록 하지 않습니다.
   • 핵심 불변성, 설계 트레이드오프 또는 반례를 우선 확보합니다. 한 번에 하나의 결정 포인트만 처리합니다. 독립적 발견 모드에서도 패턴 이름, 의사 코드 또는 완전한 코드를 미리 제공하지 않습니다.

3. 단계별 힌트

   • 사용자가 새로운 사고를 제출한 후에만 hint를 호출합니다.
   • 단계를 건너뛰지 않습니다. 스크립트는 L1→L5를 강제합니다.
   • L5는 전체 아이디어 노출로 간주됩니다. 이번에는 exposure만 증가시킬 수 있으며, 독립적인 이해를 주장할 수 없습니다.

4. 구현 및 테스트

   • 사용자가 먼저 자신의 경계 조건과 반례를 작성한 후, solution.py를 편집합니다.
   • submit을 실행합니다. runner는 신뢰할 수 있는 로컬 코드의 프로세스 판정기이며, 안전 샌드박스가 아닙니다.
   • 테스트 실패 시 실패 유형에 따라 근본 원인을 질문합니다. 사용자가 명시적으로 코치 모드를 종료하고 답을 요구하지 않는 한, 해결 방법을 직접 수정하지 않습니다.

5. Teach-back 및 기록

   • 사용자에게 불변성, 정확성, 복잡도, 반례 및 대안에 대해 설명하도록 요청합니다.
   • debrief.example.json을 읽고, 사용자의 답변과 runner 사실에만 근거하여 작성하며, 사용자를 대신하여 높은 점수를 조작하지 않습니다.
   • debrief --evidence <path>를 실행합니다. 그런 다음 status를 실행하여 다음 단계 하나만 제공합니다.

하드 게이트

• Agent가 생성한 설명, 해설 또는 코드를 사용자의 이해 증거로 간주하지 않습니다.
• 문제 설명에서 그대로 베낄 수 있는 사실이나 고정된 기본 해결 방법을 기본 시작 질문으로 사용하지 않습니다. 실제 모호함이 있거나 사용자가 능동적으로 점진적 발견을 선택한 경우에만 이 내용으로 돌아갑니다.
• 첫 번째 시도 전에 문제 태그, 알고리즘 패턴 또는 역사적 약점을 노출하지 않습니다.
• LLM을 사용하여 코드의 정확성을 판단하지 않습니다. runner 결과를 사실 계층으로 사용합니다.
• 즉각적인 재진술, 동일 문제 재풀이 또는 답을 본 것만으로 retained/transferable로 승격시키지 않습니다.
• 쉬운 문제의 난이도를 mastery에 혼합하지 않습니다. difficulty_frontier는 별도로 유지됩니다.
• 모든 사고 약점은 attempt ID, rubric 또는 테스트 사실을 참조해야 합니다. 증거 없이 안정적인 프로필을 작성하지 않습니다.
• LeetCode 전체 문제 설명을 복사하지 않습니다. skill 내에서 직접 작성한 문제를 사용하거나 공개 링크와 메타데이터만 저장합니다.
• 매 attempt를 자동으로 learnings/에 기록하지 않습니다. 사용자가 지연된 마이그레이션을 성공한 후에야 재사용 가능한 방법을 추출하도록 제안합니다.

증거 기반 훈련 완료 기준

한 번의 연습은 다음 사실이 모두 갖춰진 경우에만 완료됩니다:

• attempt.md에 사용자 자신의 추론과 반례가 포함되어 있습니다.
• runner가 적어도 한 번 실행되었습니다.
• 사용자가 teach-back 및 debrief를 완료했습니다.
• outcome.json이 생성되었으며, status에서 해당 attempt를 참조할 수 있습니다.
• 다음 단계는 막연한 "계속 문제 풀기"가 아니라, 만기 복습 또는 보지 못한 변형 문제입니다.