spar

AI가 코드를 작성하는 동안에도 계속 배우세요.

완성되었고 설득력 있는 코드를 검토하는 것은 거의 아무것도 가르쳐주지 않습니다. 그것을 판단할 입장이 없으므로, 읽고, 고개를 끄덕이고, 다음으로 넘어갈 뿐입니다.

spar는 그 입장을 돌려줍니다. 에이전트가 무엇을 작성하기 전에, 여러분은 변경이 어디에 속하는지, 어떻게 하고 싶은지, 그리고 어디에서 깨질지 말합니다. 그러면 에이전트는 그것을 구현하고, 차이를 보여주며, 여러분의 예측이 틀린 모든 지점을 기록합니다.

그런 결함들이 쌓여 여러분이 고르지 않아도 되는 커리큘럼이 됩니다. 가장 자주 놓치는 개념이 저절로 맨 위에 올라오고, 그 난이도도 그것을 따라오므로, 열심히 하기로 결심할 필요조차 없습니다.

실제 화면

› add an endpoint for cancelling an order

  spar: level 2 (skeleton), 2 open gaps on "transaction boundaries in an ORM"

  Before I write anything:
    1. Where does this belong, and why there?
    2. How would you approach it? (two sentences)
    3. Where will this go wrong?

› 1. Orders controller, calling into the service
  2. load the order, set status, save
  3. no idea

  [writes the controller, the DI wiring and the error handling,
   and leaves the one line that matters]

  // TODO(spar: decide the transaction boundary. Who opens it,
  //             and what happens if the refund call fails halfway?)

그 다섯 줄은 여러분이 직접 작성합니다. 그러면 spar done이 그것들을 에이전트가 썼을 내용과 비교하고, 각 차이를 세 가지 중 하나로 분류합니다. 무언가를 잘못 이해했거나, 무언가를 잘못 입력했거나, 여러분의 버전이 더 나은 경우입니다. 처음 두 가지의 격차로만 기록됩니다.

3주 후, 전혀 무관한 작업을 하고 있는 중에:

spar: one gap has come due. Ask them to explain "transaction boundaries in an ORM"
in their own words at the next natural pause. Do not show them the answer first.

참고로 "모르겠다"고 대답해도 괜찮습니다. 그대로 기록되며, 그 개념을 다루는 다음 작업이 여러분에게 더 적은 것이 아니라 더 많은 것을 요구할 만큼 충분히 강한 신호가 됩니다.

Related MCP server: Learning Assistant MCP Server

설치

npm i -g spar-agent
spar install                                       # finds your agents, backs up, merges
spar setup --project /path/to/repo --stack ".NET"

마지막 줄이 중요합니다: 여러분이 명명하지 않은 디렉터리에서는 아무 일도 일어나지 않습니다. 새로 설치는 완전히 무해합니다. 프로젝트를 지정하기 전까지는 ~/.spar를 만들지조차 않습니다.

spar install은 자신이 작성하지 않은 파일 측면을 조심합니다. 이미 있는 내용과 병합하고, 먼저 파일을 백업한 다음, 자신이 넣었던 항목만 대체합니다. 두 번 실행하면 두 번째 실행은 아무것도 바꾸지 않습니다. 무엇을 할지 미리 보려면 --dry-run을 사용하세요.

현재 위치

spar stats        # in the terminal
spar dashboard    # one self-contained HTML file

CALIBRATION, share of predictions that held, by week
  2026-07-13  ███████▁▁▁   67%     4/6   clean   mean level 2.3
  2026-07-20  ████▁▁▁▁▁▁   44%     4/9   clean   mean level 2.3
  2026-08-03  ████████▁▁   83%    10/12  clean   mean level 0.8
  2026-08-17  ██████████  100%     9/9   clean   mean level 0.3

CURRICULUM, concepts by weakness. The top row is what to learn next.
  * idempotency in webhooks              3 open / 3   box 1.3
    transaction boundaries in an ORM     8 open / 8   box 2.0
    EF change tracking                   0 open / 3   box 5.0

중요한 숫자는 보정(calibration)입니다. 전혀 오해를 만들어내지 않은 예측의 비율이지요. 의도적으로 결함 개수가 아닙니다. 개수는 계속 증가할 뿐이며, 여러분이 정말 좋아질 때마다 그 정확히 나빠지는 것으로 보이게 되기 때문입니다.

가상의 .NET 온보딩 6주 간의 기록입니다. 페이지는 시스템 테마를 따릅니다.

대시보드는 네트워크에 결코 닿지 않는 단일 파일입니다. CDN도, 웹 폰트도, 차트 라이브러리도 없고, 그러면 차트는 손으로 작성한 SVG입니다. 모든 숫자가 마크업 안에 있으므로, 페이지는 스크립트가 꺼져 있든, 엄격한 CSP 뒤에 있든, 또는 첨부 미리보기 안이든 똑같이 읽힙니다. 스크립트는 집중 모음 막대에만 다중 선택을 추가합니다. 그것은 5년 후에도 더블 클릭만으로 오프라인에서 열릴 것입니다.

그 안에는 연속 기록, 포인트, 배지가 하나도 없습니다. "모르겠다"는 유용한 대답인 도구에서 카운터는 단지 그럴듯한 능력을 가르칠 뿐입니다.

그래그림으로 설명

spar card --layout chain --title "Predict before you're told" \
  --subtitle "The gap between your guess and what was true is worth writing down." \
  --step "you:You predict" --step "agent:AI implements" --step "you:You compare"

카드 한 장당 한 아이디어, ~/.spar/cards/에 기록됩니다. 네 가지 배선이 대부분의 설명을 담습니다: 단계의 연쇄, 하나의 방사, 두 대상 사이의 차례, 그리고 비교.

그 한계는 권장이 아니라 강제입니다. 5단계 이상, 목록 글머리 3개 이상, 또는 네 번째 역할 색상이 들어가면 이 명령은 렌더링을 거부합니다. 그건 의도적입니다. 작은 그림의 전체 가치는 작게 유지된다는 것이고, 프롬프트에만 존재하는 규칙은 새어버리기 때문입니다. 렌더링되지 않는 경우 답은 카드 두 장입니다.

색은 그것이 무엇인지를 표시할 뿐, 몇 번째 단계인지를 표시하지 않으므로, --step "you:..."는 여러분이 만드는 모든 카드에서 you를 같은 색으로 유지합니다. ~/.spar/config.json의 cards.theme가 스타일을 고르는 것입니다: neon (기본값, 어두운 배경에 윤곽을 강조한 사각형) 또는 plain.

레벨

레벨 2와 3에서 에이전트는 항상 실패하는 테스트를 남기며, 그렇지 않으면 spar는 인계를 거부합니다. 테스트가 없는 마커는 대조할 무엇과 비교할 추측만 손에 넣으므로 회색이 맞았는지 알아내기 위해 에이전트에게 물을 수밖에 없습니다. 이것이야말로 이 도구가 존재하는 목적인 의존성입니다. 테스트가 있어야 20분 동안 혼자 일해도 올바른지 알 수 있습니다.

프로젝트에 testCommand를 나열하면 spar는 인계 시점에 테스트 스위트를 그대로 실행하고, 그것이 붉은 상태(실패)가 될 것으로 기대합니다. 이미 빈 스텁을 통과하는 테스트는 아무것도 못 고정하지 때문입니다:

spar setup --project "$(pwd)" --test-command "npm test"

이 검사는 기본적으로 꺼져 있습니다. 남의 테스트 스위트를 자동 실행하는 것은 침습적이고 느릴 수 있습니다.

완전히 끄는 스위치는 없으며 레벨 0만 있을 뿐입니다. 여러분 자체의 결함 로그가 레벨을 제안하고 그 이유를 설명하며, 언제나 그것을 덮어쓸 수 있습니다. 덮어쓴 것도 집계됩니다. 어떤 사람이 그 제안을 계속 고쳐 쓰고 있다면 그것은 임곗값이 잘못되었다는 말이기 때문입니다.

여러 단계에 걸쳐 티켓 작업하기

spar plan --from docs/plan.md          # reads ## Task / ### Task headings
spar plan --step "..." --step "..."    # or name the steps yourself
spar plan                              # where am I
spar step done --session <id>

계획이 활성화되어 있으면 단계가 곧 작업입니다. 침묵을 추측하는 대신 각 단계마다 게이트가 한 번 작동하며, 각 단계는 여러분의 결함 로그에서 레벨을 부여받습니다. 그리고 예측은 세션이 아닌 그 단계에 붙어 있으므로 그 일이 여전히 나중에도 유지됩니다.

바로 그 세밀함이 핵심입니다. "여기가 어긋날까?"는 "취소 엔드포인트를 추가"에 대한 진짜 질문이며, "환불과 함께 취소를 구현"에 대한 추측일 뿐이고, 추측은 보정 수치가 아무것도 측정하지 못하게 만듭니다.

spar는 계획을 세우지 않습니다. 에이전트가 티켓을 읽고 여러분의 플래너가 작업을 분할합니다. spar는 각 단계에서 여러분의 뜻이 얼마나 될지 결정합니다. 계획은 프로젝트의 .spar/에 있으며, spar는 그 생성 즉시 .gitignore에 추가합니다.

에이전트별로 받는 것

MCP는 훅과 달리 표준화되어 있으므로, 그 서버는 별다른 구현 없이도 모든 MCP 클라이언트에 도달합니다. 그 서버가 할 수 없는 유일한 일은 게이트입니다. MCP 서버는 도구를 제공하고 호스트 자신이 쓰는 행위를 가로챌 수 없기 때문입니다. 그 한계가 에이전트별 훅 어댑터를 관리해야 하는 근본 이유이며, 자율적인 능력이 좋은 짋 기회이지만 열악한 것만으로는 대체 할 수 없는 이유이기도 합니다.

플러그인으로 설치

/plugin marketplace add Lander-Parren/spar

그렇게 해서 두 개의 플러그인이 설치됩니다. spar는 이 저장소입니다. humanizer는 선택 기능이며 제 것이 아닙니다: blader/humanizer, MIT, Copyright (c) 2025 Siqi Chen, main 브랜치를 따라서 특정 커밋에 고정되어 전달됩니다.

이것은 spar 안에 복사되지 않고 함께 나와 나열되므로 그 자신의 저장소에서 업데이트되고 저자도 유지됩니다. 존재하는 이유가 있다면: spar는 일생 여정에서 여전히 혼란스러워하는 사람에게 설명하기 위해 쓰이며, 기계가 만든 것처럼 읽히는 설명은 최대한 빨리 그 사람을 잃는 방아쇠입니다. spar 자체의 스킬에는 그것을 설치하지 않는 사람들을 위한 그 규칙을 짧게 담겨 있습니다.

하지 않는 것

모든 것은 여러분의 기계, 즉 ~/.spar/ 안에 있습니다. 계정, 원격 분석, 네트워크 호출, 자체 API 키가 없습니다. 로그에는 사업 로직이 아니라 개념과 잘못된 이해를 담으므로, 동료에게 스크린샷을 공유하셔도 안전합니다.

그리고 언제나 "없는" 것은 아무것도 없습니다. 실패에 닿아 열리는 방식을 취합니다. 바이너리가 없거나, 설정 파일이 깨지거나, 자체 코드에 버그가 있어도: 게이트는 열리고 여러분은 진행합니다. 학습 도구가 출시라는 때의 이유가 되어서는 안 됩니다.

작업당 한 번이지, 파일당 한 번이 아닙니다. 하나의 예측 뒤에 있는 열다섯 번의 편집이 게이트 하나를 소요합니다.

쓰기 도구뿐 아니라 쉘 명령도 감시합니다. 에이전트는 전용 쓰기 툴보다 cat > file <<EOF 또는 perl -0pi를 훨씬 자주 사용합니다. 일부 설정은 그것을 그렇게 하도록 명시적으로 지시하기도 합니다. 쉘 명령이 작성되는 프로젝트 내부 어딘가에 실제 기록을 남길 때만 멈춥니다: 리다이렉션, tee, 제자리 sed와 perl이다, cp와 mv의 위치, 쓰기 위해 파일을 여는 인터프리터 한 줄짜리 명령입니다. 파일을 읽거나 테스트 실행하는 것은 그대로 통과합니다. 쉘은 정규식으로 구문분석할 수 없으므로, 이것은 의도적으로 보수적이며 평범한 작업을 막는 대신 드문 형태를 그냥 흘려보냅니다.

작업은 그 안에서 진전이 있는 동안 계속 살아 있으며, 30분 간의 침묵가 지나고 나면 유효가 끝납니다(~/.spar/config.json의 idleMinutes). 이는 나이를 재는 것이 아니라 유휴함을 재므로 긴 조심스런 작업 중간에 방해받는 일은 없습니다. 타이머가 끝나기 전에 새로운 작업을 시작한다면, spar next --session <id>가 이어서 그것을 즉시 다시 준비시킵니다.

그 편향은 고의적입니다. 이어지는 일로 게이트를 다시 준비하면 삼십초가 들고 여러분은 spar rush로 밀리게 되는 것이, 그렇게 해서 이런 도구는 죽게 됩니다. 한 면, 사이 하나를 놓치면 결점 하나의 비용으로 끝나며, 그 개념은 다시 한 번 찾아옵니다.

하나의 빈틈은 세션이 시작될 때, 다음 자연적 위일의 질문 형태로 돌아옵니다. 결코 목록이 되거나 방해가 되지 않습니다. 그 질문에 잘 대답하면 상자 한 칸 올라갑니다(1, 3, 7, 16, 35일). 형편없이 대답하면 내일 다시 시작합니다.

별도로 나뉘어 있는 앱, 또는 가볍을 넘기기 위한 편지함은 넣지 않습니다. 이미 여러분이 겪고 있는 세션 안으로 도착하기 때문입니다.

부담 없이 시도해 보기

example/은 의존성이 없는 작은 TypeScript 프로젝트로, sil 주목하도록 만들어졌습니다.

cd example
spar setup --project "$(pwd)" --stack "TypeScript"

그 다음 에이전트에게 주문 취소를 추가해달라고 요청하고, 게이트가 멈추는 것을 보세요. example/README.md이 무엇을 찾아야 하는지 설명합니다.

설명이 있는 위치

명령은 사실을 내놓습니다. 지침(skill)은 그 사실을 어떻게 할 것에 설명합니다. spar done은 diff를 출력하고, 무엇을 잘못 알고 있는지 오타인지의 판단은 스킬에 들어 있습니다. 게이트는 아직 게이트를 통과하지 못한 작업을 알리고 어떤 명령에 뚫었는지 나열합니다. 먼저 예측해야 하는 이유는 스킬이 설명합니다.

그렇게 나누면 절차가 스킬을 읽을 수 있는 어떤 클라이언트에서도 읽을 수 있고, 출시를 기다리지 않아도 변경할 수 있습니다. 스킬을 읽을 수 없는 에이전트를 위해, spar guide <주제>는 동일한 파일에서 같은 부분을 출력합니다:

spar guide                       # list the topics
spar guide the-closing-review

한 소스, 전달할 두 가지 방법이므로 두 것은 분리되어 버리기 새지 않습니다. 훅이 가리키는 모든 지점이 실제로 있는지 테스트가 검증하기 때문에 제목을 바꾸면 페이지가 사라진 것에 잘못 보내는 대신 빌드가 자동으로 깨지게 됩니다.

npm install
npm test              # spar's own suite
npm run build
npm run emit          # regenerate the checked-in hook configs
npm run validate:example   # drive every hook end to end against example/

validate:example는 배선 문제를 잡는 테스트입니다. 유닛 테스트는 각 조각을 증명하고, 이 스크립트는 버려도 되는 홈 디렉터리에서, 우리가 빌드된 바이너리를 상대로 실제 훅 페이로드가 의도하는 결정을 만들어내는지 증명합니다.

같은 훅 정의는 세 번에 걸쳐 저장됩니다: Claude Code의 플러그인 레이아웃, Agent Plugins 네임스페이스, 그리고 Cursor의 까지 입니다. 두 개의 표준은 클라이언트 전용 파일이 어디에 위치해야 하는지에 대해 이견이 있으므로, 두 형태를 모두 들어맞게 한 개의 위치를 정합니다. 세 가지 모두 src/core/hookconfig.ts를 통해 npm run emit으로 생성되며, 이들의 차이가 생기면 그 순간 테스트는 실패합니다.

라이선스

MIT