Jaekit 이해하기

한국어 · English

Jaekit은 Claude Code·Codex에 맡긴 작업이 정말 끝났는지 기록으로 확인하게 해 주는 도구입니다. 에이전트에 더해 쓰는 플러그인 Spec·Seal·Spar와 터미널 프로그램 ha·spar로 이루어집니다. 일을 맡기기 전에 무엇을 하면 끝인지 문서로 정해 두고, 끝났는지는 에이전트의 말이 아니라 검사를 실제로 돌린 기록으로 판단합니다.

이 문서는 Jaekit을 처음 보는 사람을 위해 다음을 차례로 설명합니다.

• 왜 필요한지
• 쓰면 무엇이 달라지는지
• 누가 무엇을 하는지
• 목표 하나가 어떻게 지나가는지
• 완료가 무엇을 뜻하는지

다 읽은 뒤에는 설치 안내로 설치하고 README의 첫 작업 맡기기를 따라 해 봅니다.

에이전트가 "다 했습니다"라고 할 때#

Claude Code나 Codex에 일을 맡기면 이런 일이 생기곤 합니다.

• 조건 열 개 중 일곱 개만 하고 끝냅니다.
• 어려운 조건을 쉬운 조건으로 바꿔 읽습니다.
• 일찍 멈춰서 "빠진 것 마저 해줘"를 되풀이하게 됩니다.
• "테스트를 통과했습니다"라고 하지만, 무엇을 어떻게 확인했는지는 바뀐 코드를 처음부터 읽어야 압니다.
• 대화가 끊기면 무엇을 약속했고 어디까지 확인했는지 다시 설명해야 합니다.

에이전트를 단계마다 승인하며 묶어 두면 이런 일은 줄지만, 일을 맡긴 의미가 줄어듭니다. 보고를 그대로 믿으면 편하지만, 에이전트는 자기 검사를 고치거나 쉬운 기준을 쓸 수 있습니다. "테스트 통과"는 "목표 달성"과 같지 않습니다.

Jaekit의 생각: 일은 맡기고, 끝은 기록으로#

Jaekit은 세 가지만 붙잡고 나머지는 에이전트에게 맡깁니다.

1. 목표는 내가 정합니다. 무엇을 하면 끝인지, 즉 완료 조건을 일을 시작하기 전에 문서로 정합니다. 구현하는 동안 에이전트는 이 문서를 고치지 않습니다.
2. 일은 에이전트가 합니다. 계획, 순서, 도구는 에이전트가 정합니다. 단계마다 승인하지 않고, 결과를 바꾸는 결정이 필요할 때만 묻습니다.
3. 완료는 기록으로 판단합니다. 필수 완료 조건마다 검사 기록이 있어야 완료가 남습니다. 자동으로 확인할 수 없는 조건은 내 확인을 기록해 채웁니다. 새로 생기는 동작이라면 그 검사가 바꾸기 전 코드에서는 그 동작이 없어 실패하고, 바꾼 뒤에는 통과해야 합니다. 바꾸기 전에도 통과하는 검사로는 새 동작이 생겼는지 알 수 없기 때문입니다. 기존 동작을 지키는 검사는 처음부터 통과해도 됩니다.

쓰면 무엇이 달라지나요#

같은 일을 대화로만 맡길 때와 Jaekit으로 맡길 때를 나란히 놓으면 이렇습니다. 어느 쪽이든 일은 같은 에이전트가 합니다. 달라지는 것은 기록입니다.

누가 무엇을 하나요#

일하는 주체는 쓰던 에이전트 하나입니다. Spec과 Seal은 에이전트가 따르는 지침이고, ha와 Spar는 에이전트가 실행하는 도구입니다. 이 문서에서 "Spec이 쓴다", "Seal이 계획한다"는 에이전트가 그 지침을 따라 한다는 뜻입니다.

Spec·Seal·Spar는 Claude Code나 Codex에 설치하는 플러그인이고, ha와 spar는 에이전트가 실행하는 터미널 프로그램입니다.

목표 하나가 지나가는 길#

로그인 화면에 "비밀번호 찾기" 링크를 더하는 가상 예시로 따라가 봅니다. 실제로 실행하거나 검증한 사례가 아닙니다.

1. 요청합니다. 에이전트 대화에 /spec:spec 로그인 화면에 "비밀번호 찾기" 링크를 추가해줘라고 보냅니다(Codex는 $spec:spec).
2. Spec이 목표를 씁니다. docs/specs/password-link/SPEC.md에 목표와 완료 조건을 적습니다. 완료 조건에는 번호가 붙습니다. 예를 들어 AC-1 "로그인 화면에 재설정 페이지로 가는 링크가 보인다", AC-2 "기존 로그인은 그대로 동작한다"입니다. 검토 등급도 제안하고, 정할 것이 남지 않았으면 지금 구현할지 한 번 물은 뒤 멈춥니다.
3. 확인하고 "응"이라고 답합니다. 빠진 조건이 있으면 고쳐 달라고 합니다. 맞으면, 지금 구현할지 묻는 질문에 "응"이라고 답합니다. 그때부터 Seal이 시작됩니다.
4. Seal이 계획합니다. PLAN.md에 조건마다 검사 방법을 적습니다. AC-1은 새로 생기는 동작이고, AC-2는 계속 지켜야 하는 동작입니다.
5. ha가 검사하고 기록합니다. 에이전트는 AC-1의 검사를 바꾸기 전의 코드에서 먼저 돌려, 링크가 아직 없어 실패하는 것을 기록합니다. 그다음 구현하고 다시 돌려 통과를 기록합니다. AC-2는 통과 기록을 남깁니다. 모든 실행은 runs.jsonl에 한 줄씩 쌓입니다.
6. Spar가 독립 검토를 합니다. 이 목표의 등급은 standard라서, 완료 전에 다른 맥락의 리뷰어들이 변경을 검토합니다. 고칠 지적이 있으면 에이전트가 고치고, 끝난 검토를 gate로 기록합니다.
7. ha done이 완료를 기록합니다. 필수 조건이 모두 충족되고 검토 기록 같은 나머지 요건도 갖추면 완료 기록이 남고, 보고가 PROGRESS.md에 붙습니다.
8. 보고를 읽습니다. 바뀐 것, 확인한 것, 직접 볼 것, 남은 한계, 다음 행동 다섯 줄과 조건별 근거를 보고, 실제 결과도 함께 확인합니다. 0.1.24 이상으로 시작해 완료한 목표에서는 판단 문장이 ## 검수 요약에 있습니다.

중간에 대화가 끊기면 같은 프로젝트의 새 대화에서 docs/specs/password-link 이어서 해줘라고 보냅니다. 새 대화의 에이전트가 목표 폴더와 ha가 계산한 상태를 읽고 남은 일을 이어 갑니다.

무엇이 남나요#

목표마다 프로젝트 안에 폴더 하나가 생깁니다. 모두 보통 파일입니다.

검수 요약. 0.1.24 이상으로 시작한 목표에서는 완료 기록 뒤 ## 현재 바로 다음의 ## 검수 요약이 검수를 시작하는 곳입니다. 맨 위 줄에 완료 기록, 보증 등급, 충족한 필수 조건 수, 검토 gate 결과, 이 변경이 하는 일, 먼저 볼 것이 있고, 그 아래에 바뀐 동작과 파일, 범위 밖이나 기존 것을 바꾼 곳, 근거, 누가 정했나, 직접 볼 것, 보지 않은 것, 자세히가 이 순서로 옵니다. 해당하는 것이 없는 항목에는 없음을 쓰고, 목표를 다시 열어 완료를 다시 기록하면 새 완료 기록 기준으로 다시 씁니다. 사용자의 언어로 쓰고, 기록은 무엇인지를 먼저 쓰며, 항목마다 짧게 쓰고 seq는 보조로만 붙입니다. 검증 출력과 지적 원문은 옮기지 않고 지적은 ID, 한 줄 요약, 끝만 적습니다. Seal의 판단은 이 절에만 있고, ## 완료 보고에는 ha report 출력과 이 절을 가리키는 한 줄이 있습니다. 완료한 목표는 ## 검수 요약부터 읽습니다. 멈춘 목표와 그 전 Seal로 시작한 목표는 지금처럼 ## 완료 보고를 읽습니다.

새로 시작한 목표의 완료 보고는 맨 위 다섯 줄을 ha가 실행 기록, Git, 목표 문서로 계산합니다. 에이전트가 고쳐 쓰지 않습니다. 보고에 나오는 낱말은 이렇게 읽습니다.

• base: 작업을 시작한 commit입니다.
• seq: 기록의 번호입니다. 완료 기록 seq 6은 완료를 남긴 여섯 번째 기록입니다.
• 보증 수준 local: 이 컴퓨터에서 얻은 근거라는 뜻입니다.
• 검사 작성자: 실행자: 구현한 에이전트가 검사도 직접 썼다는 뜻입니다.

더 자세한 읽는 법은 사용 안내에 있습니다.

검토 등급#

목표 문서의 Assurance: 줄이 독립 검토를 얼마나 받을지 정합니다. Spec이 변경의 크기와 위험을 보고 제안하고, 다른 등급을 원하면 "strict로 해줘"처럼 말합니다. 프로젝트 지침이 더 많은 검토를 요구하면 그쪽을 따릅니다.

지금의 Seal로 새로 시작한 standard·strict 목표는 Spar 검토 기록이 있어야 완료됩니다. 이전 버전으로 시작한 목표는 시작할 때의 규칙을 따릅니다. Spar를 처음 쓰기 전에는 프로젝트 준비가 한 가지 필요합니다. README의 첫 standard 목표 전에를 봅니다. 리뷰어에게 무엇이 전송되는지는 Spar 안내에 있습니다.

완료가 뜻하는 것과 뜻하지 않는 것#

완료 기록이 있다는 것은 다음을 뜻합니다.

• 필수 완료 조건마다 검사 기록 또는 필요한 사용자 확인이 있습니다.
• 새로 시작한 목표라면, 필수 조건 가운데 새 동작의 검사는 바꾸기 전에 그 동작이 없어 실패하고 바꾼 뒤에 통과한 기록이 있습니다.
• 새로 시작한 standard·strict 목표는 완료를 기록할 때의 코드와 목표 문서를 검토한 Spar 기록(검토 gate)이 있습니다.

다음은 뜻하지 않습니다.

• 결과 전체에 결함이 없다는 것. 검사가 목표를 충분히 덮는지는 프로그램이 자동으로 판단할 수 없습니다. 그래서 독립 검토와 사용자 확인으로 보완합니다.
• 독립된 제3자의 검증. 보증 수준은 local입니다. 검사는 에이전트가 작성하고, 같은 사용자 권한의 에이전트는 검사와 기록 파일을 바꿀 수 있습니다. 기록의 줄 사이 연결은 앞선 기록을 고치거나 지운 것을 드러낼 수 있지만, 마지막 줄의 변경이나 작정한 위조까지 막지는 못합니다.
• 배포와 설치. 기본 결과는 로컬 변경과 commit까지입니다. push, PR, 배포는 따로 하거나 일반 에이전트에 요청합니다.

Jaekit은 에이전트를 감시하는 보안 도구가 아닙니다. 무엇이 실제로 확인됐고 무엇이 확인되지 않았는지를 드러내는 도구입니다.

자주 묻는 질문#

터미널과 에이전트 대화에는 각각 무엇을 입력하나요? 터미널에는 주로 설치와 업데이트 명령을 입력합니다. 상태나 기록을 직접 보고 싶을 때, Spar 리뷰어를 설정할 때도 터미널을 씁니다. 에이전트 대화에는 /spec:spec <요청>(Codex는 $spec:spec), 목표를 확인한 뒤의 "응", 질문에 대한 답, 그리고 대화가 끊겼을 때의 docs/specs/<goal> 이어서 해줘를 보냅니다. ha와 spar 명령은 에이전트가 실행합니다.

우리 프로젝트에 무엇이 생기나요? 목표마다 docs/specs/<goal>/ 폴더가 생깁니다. 이 폴더를 Git으로 추적할지는 프로젝트 정책에 따릅니다. 기록에는 내가 한 말과 작업 경로가 들어갈 수 있으니, 공개 저장소에 올리기 전에는 내용을 확인합니다. Spar를 쓰는 첫 standard·strict 목표 전에는 .gitignore에 docs/reviews/를 더합니다.

이미 있는 테스트는 어떻게 쓰나요? 기존 테스트 전체는 "기존 동작이 그대로인지"를 확인하는 조건의 검사로 쓸 수 있습니다. 어떤 조건을 무엇으로 검사할지는 에이전트가 PLAN.md에 적습니다. 자세한 형식은 실행 묶음 계약에 있습니다.

끝나면 push나 PR, 배포까지 해 주나요? 아닙니다. 기본 결과는 로컬 변경과 commit까지입니다. push와 PR은 직접 하거나 일반 에이전트에 따로 요청합니다.

우리 코드가 밖으로 나가나요? ha는 AI 모델을 부르지 않습니다. Spar 리뷰어는 기준·규칙 문서와 변경 내용(diff)을 각자의 제공자에게 보내고, 리뷰어가 읽은 프로젝트 파일도 함께 갈 수 있습니다. 기본 리뷰어라면 claude는 Anthropic, codex는 OpenAI, agy는 Google입니다. 밖으로 나가면 안 되는 코드라면 Spar를 돌리지 않습니다. 자세한 내용은 Spar 안내에 있습니다.

다음에 읽을 것#

• 설치하고 첫 목표를 맡기려면: README의 시작하기
• 목표를 고치고, 이어 가고, 보고를 읽으려면: 사용 안내
• 독립 검토를 설정하려면: Spar 안내
• 멈춘 이유와 보고의 근거를 자세히 읽으려면: 작업 상태와 완료 보고 읽기
• 파일과 기록의 정확한 형식은: 계약 문서