README
¶
한국어 · English
설치 · 첫 작업 · 사용 안내
Jaekit은 Codex·Claude Code로 맡긴 프로젝트 작업의 목표와 확인 기록을 남기는 도구입니다. Spec은 원하는 일과 완료 조건을 정리하고, Seal은 에이전트가 그 목표에 따라 작업을 이어 가고 확인 기록을 남기도록 합니다. 대화가 끊겨도 저장된 진행 상황에서 이어 갈 수 있습니다.
현재 배포판은 v0.1.4, 실제 작업에 써 보며 다듬는 초기 개발 단계입니다.
Jaekit 소개 이미지 보기
사용 흐름
Spec은 목표 문서를 작성한 뒤 멈춥니다. 내용을 확인하고 별도 메시지로 Seal을 시작하면 Codex·Claude Code의 에이전트가 구현·검사·수정을 진행합니다. 매 단계 승인할 필요는 없으며, 결과를 바꾸는 결정이나 직접 확인이 필요할 때 답합니다.
필수 완료 조건이 충족되면 완료 기록과 보고를 남깁니다. 무엇을 바꿨고 어떻게 검사했는지, 실제 결과와 함께 확인하세요.
시작하기
설치
아래는 macOS + Codex로 시작하는 순서입니다. Homebrew(프로그램 설치 도구), Git, Codex CLI, Git으로 관리하는 작업할 프로젝트 폴더가 필요합니다. Jaekit 저장소를 clone할 필요는 없습니다.
Claude Code는 Claude Code 설치, Linux 또는 Homebrew 없는 환경은 설치 안내를 따릅니다. Windows에서는 기록 도구 ha가 지원되지 않아 Seal을 쓸 수 없습니다. Spec은 ha가 필요 없지만 Windows의 설치·동작은 아직 확인하지 않았습니다.
1. 터미널에서 기록 도구 ha를 설치합니다. 아래 블록을 하나씩 실행하고 끝날 때까지 기다립니다.
brew install jgoneit/tap/jaekit
ha --version
ha 0.1.4가 나와야 합니다. 명령을 찾지 못하거나 버전이 다르면 버전 확인을 봅니다.
2. 같은 터미널에서 Codex 플러그인을 설치합니다.
codex plugin marketplace add jgoneit/jaekit@v0.1.4
codex plugin add spec@jaekit
codex plugin add seal@jaekit
설치 후 Codex를 새로 엽니다. @v0.1.4는 사용할 배포판을 고정합니다. 이미 설치했다면 업데이트 또는 기존 로컬 설치에서 전환을 먼저 확인합니다.
첫 작업 맡기기
작업할 프로젝트 폴더에서 Codex CLI 또는 데스크톱 앱을 엽니다. 이제부터는 터미널이 아니라 에이전트 대화에 입력합니다.
1. Spec에 요청합니다. $를 입력하고 목록에서 Jaekit의 spec:spec을 고른 뒤, 원하는 작업을 적습니다.
$spec:spec 로그인 화면에 "비밀번호 찾기" 링크를 추가해줘
위 요청은 재설정 페이지가 이미 있는 프로젝트를 가정한 가상 예시이며, 실행하거나 검증을 마친 사례가 아닙니다. 실제 프로젝트에서 원하는 작업으로 바꿔 보내세요.
2. 목표를 확인합니다. Spec이 알려 준 문서를 읽고 수정할 내용을 말합니다. 이 예시라면 “새 링크가 기존 재설정 페이지로 연결되는지”, “기존 로그인이 그대로 동작하는지”가 완료 조건입니다.
3. 별도 메시지로 Seal을 시작합니다. $ 목록에서 Jaekit의 seal:seal을 고르고 목표 폴더를 지정합니다.
$seal:seal docs/specs/<goal>
<goal>은 Spec이 알려 준 실제 목표 폴더 이름으로 바꾸는 자리입니다. 이름이 password-link라면 전체 경로는 docs/specs/password-link입니다. Claude Code의 /spec:spec·/seal:seal 호출은 사용 안내를 참고하세요.
대화가 끊겼다면
같은 프로젝트 폴더에서 새 대화를 열고 이전에 작업한 목표를 지정합니다. <goal>을 실제 폴더 이름으로 바꾸면 저장된 목표와 진행 기록에서 이어 갑니다.
docs/specs/<goal> 이어서 해줘
쓰기 전에 알아두면 좋은 점
완료 보고에서는 무엇을 확인하나요?
필수 완료 조건은 검사 기록 또는 필요한 사용자 확인으로 충족돼야 합니다. 자동 검사는 에이전트가 작성하므로, 완료가 결과 전체의 무결함이나 독립된 제3자의 검증을 보장하지는 않습니다. 보고의 가정·남은 한계와 실제 결과를 함께 확인합니다.
기본 작업 결과는 로컬 변경과 commit(변경 이력 저장)까지입니다. GitHub에 올리거나 PR을 만들고 배포하는 일은 직접 하거나 일반 에이전트에 별도로 요청합니다. 완료 보고 읽기
목표만 정리해도 되나요?
네. Spec은 Seal·ha 없이 사용할 수 있습니다. 목표를 정리해 두고 구현할 준비가 됐을 때 Seal을 시작하세요.
어떤 기록이 남나요?
프로젝트에 목표 문서, 작업 계획, 진행·완료 보고와 실행 기록이 남습니다. 진행 보고는 목표 폴더의 PROGRESS.md에서 볼 수 있습니다. 설치·업데이트·제거는 이 기록을 지우지 않습니다. Git 추적은 프로젝트 정책을 따르며, 공개 전에는 내용을 확인합니다. 저장되는 파일
더 알아보기
사용 경험이나 막힌 점은 사용 보고·설치·버그 issue로 남겨 주세요. issue는 공개되므로 회사 코드, 내부 이름, 비밀 값과 로그 원문은 제외해 주세요.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ha
command
Command ha is Seal Core: it runs verification commands without a shell, appends the run record, computes goal state deterministically, and records completion.
|
Command ha is Seal Core: it runs verification commands without a shell, appends the run record, computes goal state deterministically, and records completion. |
|
internal
|
|
|
bundle
Package bundle reads the execution bundle (contracts/bundle.md) of a goal directory and lints it against the goal documents.
|
Package bundle reads the execution bundle (contracts/bundle.md) of a goal directory and lints it against the goal documents. |
|
diag
Package diag holds the lint problem type shared by the goal document and execution bundle parsers.
|
Package diag holds the lint problem type shared by the goal document and execution bundle parsers. |
|
evidence
Package evidence binds a declared behavioral check to one process invocation.
|
Package evidence binds a declared behavioral check to one process invocation. |
|
gitx
Package gitx calls the user's git CLI with explicit argv.
|
Package gitx calls the user's git CLI with explicit argv. |
|
goaldocs
Package goaldocs reads goal documents (contracts/goal-docs.md) as a reader: SPEC.md, the auxiliary documents it links inside the goal directory, the criterion IDs, and the optional work breakdown proposal.
|
Package goaldocs reads goal documents (contracts/goal-docs.md) as a reader: SPEC.md, the auxiliary documents it links inside the goal directory, the criterion IDs, and the optional work breakdown proposal. |
|
markdown
Package markdown reads the small Markdown subset that the Jaekit contracts rely on: headings, pipe tables, list items, inline code spans, and relative links.
|
Package markdown reads the small Markdown subset that the Jaekit contracts rely on: headings, pipe tables, list items, inline code spans, and relative links. |
|
record
Package record reads and appends the run record `runs.jsonl` (contracts/run-record.md, schema run/v1).
|
Package record reads and appends the run record `runs.jsonl` (contracts/run-record.md, schema run/v1). |
|
run
Package run executes a verification command as argv, without a shell, and keeps its combined output in a local log file.
|
Package run executes a verification command as argv, without a shell, and keeps its combined output in a local log file. |
|
status
Package status computes the state of a goal from the run record, the execution bundle, and git (contracts/run-record.md §3–§5).
|
Package status computes the state of a goal from the run record, the execution bundle, and git (contracts/run-record.md §3–§5). |