hatice: 에이전트 중심 시대를 위한 자율적 이슈 오케스트레이션

에이전트 중심 시대를 위한 자율적 이슈 오케스트레이션 (Autonomous issue orchestration).

Hatice는 이슈 트래커 (issue tracker)를 폴링(poll)하고, 격리된 워크스페이스 (isolated workspaces)를 생성하며, 각 이슈를 엔드 투 엔드 (end-to-end)로 해결하기 위해 Claude Code 에이전트 (agents)를 파견합니다. 배정, 다회차 실행 (multi-turn execution), 지수 백오프 (exponential backoff)를 통한 재시도, 조정 (reconciliation), 그리고 실시간 관찰성 (real-time observability)을 포함한 전체 라이프사이클 관리를 지원합니다.

"인간은 조종하고, 에이전트는 실행한다." 이 프로젝트는 Harness Engineering 선언문을 수용합니다. 즉, 엔지니어의 역할은 더 이상 코드를 작성하는 것이 아니라, 코딩 에이전트가 신뢰할 수 있는 작업을 수행할 수 있도록 환경을 설계하고, 의도를 명시하며, 피드백 루프 (feedback loops)를 구축하는 것이라는 아이디어입니다. OpenAI는 Codex를 통해 이를 입증했습니다. Hatice는 Claude Code Agent SDK를 기반으로 구동되는 동일한 철학의 작동 가능한 오픈 소스 구현체입니다.

hatice-01-gh.mp4

2026년 2월, OpenAI는 모든 코드 라인이 에이전트에 의해 작성되며, 엔지니어는 스캐폴딩 (scaffolding), 명세 (specification), 그리고 레버리지 (leverage)에 집중하는 소프트웨어 개발의 근본적인 재사고인 "Harness Engineering"을 발표했습니다.

명세 기반 개발 (Specification-driven development)— 단 하나의 WORKFLOW.md 파일이 트래커 설정, 워크스페이스 훅 (workspace hooks), 에이전트 동작, 그리고 작업 프롬프트 (task prompt)를 정의합니다. 에이전트는 이를 읽고, 인간은 이를 작성합니다.

시스템 기록으로서의 저장소 지식 (Repository knowledge as system of record)— .claude/CLAUDE.md는 TDD 방법론, 아키텍처 제약 조건, 그리고 코딩 표준을 인코딩합니다. 에이전트는 이를 자동으로 따릅니다.

수동 수정 대신 피드백 루프 (Feedback loops over manual fixes)— 에이전트가 실패하면, Hatice는 지수 백오프 (exponential backoff)를 사용하여 재시도하고, 트래커 상태를 재확인하며, 조정 (reconciles)합니다. 시스템이 스스로 수정합니다.

병렬 에이전트 오케스트레이션 (Parallel agent orchestration)— 여러 에이전트가 서로 다른 이슈에 대해 독립적인 세션을 가진 격리된 워크스페이스에서 동시에 작업합니다.

관찰성 우선 (Observability-first)— 실시간 SSE 대시보드, 터미널 ANSI 디스플레이, 세션별 로그, 속도 제한 (rate limit) 추적, 그리고 토큰 계정 (token accounting)을 제공합니다. 에이전트가 수행하는 모든 것을 볼 수 있습니다.

이것은 단순한 래퍼(wrapper)나 장난감이 아닙니다. 이것은 대규모로 자율 코딩 에이전트 (autonomous coding agents)를 실행하기 위해 구축된 프로덕션급 오케스트레이션 (orchestration) 시스템입니다 — 4,148줄의 애플리케이션 코드, 6,669줄의 테스트 코드, 30개 파일에 걸친 328개의 테스트 케이스, 타입 에러(type error) 0건 — 을 자랑합니다.

Hatice는 OpenAI의 Codex 에이전트를 위한 Elixir/OTP 오케스트레이션 시스템인 Symphony에서 보여준 아키텍처 패턴에서 영감을 받았습니다. 우리는 모든 구성 요소를 TypeScript로 처음부터 재구상하였으며, Codex를 Claude Code Agent SDK로 교체하고 기존의 기능을 넘어서는 역량을 추가했습니다.

코드를 복사하지 않았습니다. 라이선스를 위반하지 않았습니다. 우리는 선언문 (manifesto)을 채택하고, 아키텍처를 연구하여, 새로운 것을 구축했습니다.

기능 (Capability)	Symphony (Elixir/Codex)	Hatice (TypeScript/Claude)
런타임 (Runtime)	Elixir/OTP (BEAM VM)	Node.js 20+ / Bun
에이전트 SDK (Agent SDK)	Codex JSON-RPC over stdio	Claude Code Agent SDK `query()`
웹 프레임워크 (Web Framework)	Phoenix + LiveView (WebSocket)	Hono + SSE (EventSource)
설정 검증 (Config Validation)	NimbleOptions	Zod v4
템플릿 엔진 (Template Engine)	EEx	LiquidJS
로깅 (Logging)	Elixir Logger	Pino (구조화된 JSON)
CLI	OptionParser	Commander.js
프로세스 감독 (Process Supervision)	OTP Supervisor (네이티브)	커스텀 Supervisor 클래스
PubSub	Phoenix.PubSub	와일드카드가 포함된 Typed EventBus
실시간 대시보드 (Real-time Dashboard)	Phoenix LiveView	SSE + vanilla JS
이슈 트래커 (Issue Tracker)	Linear 전용	Linear + GitHub Issues + GitLab
테스트 프레임워크 (Test Framework)	ExUnit (~17개 파일)	Vitest (30개 파일, 328개 테스트)
모델 선택 (Model Selection)	고정됨 (Codex)	설정 가능 (`claude.model`)
비용 추적 (Cost Tracking)	사용 불가	세션당 USD 추적
캐시 토큰 메트릭 (Cache Token Metrics)	사용 불가	`cacheRead/CreationInputTokens`
도구 제어 (Tool Control)	승인 정책 (Approval policy)	`allowedTools` / `disallowedTools` + `canUseTool`
MCP 도구 (MCP Tools)	사용 불가	`linear_graphql` + `github_graphql`
워크스페이스 아티팩트 (Workspace Artifacts)	`.elixir_ls` 정리	8-패턴 임시 디렉토리 정리
홈 디렉토리 확장 (Home Dir Expansion)	사용 불가	설정 경로 내 `~/` 지원
세션별 로그 (Per-session Logs)	LogFile 모듈	세션별 Pino NDJSON 파일

GitHub Issues 지원— Linear뿐만 아니라 owner/repo 형식의 완전한 REST + GraphQL 어댑터를 지원합니다.
GitLab 지원— GitLab CE/EE를 위한 완전한 REST 어댑터를 제공합니다. 인시던트 심각도(severity)를 우선순위(priority)로 매핑하는 기능과 셀프 호스팅(self-hosted) 인스턴스를 지원합니다.
Claude Code Agent SDK— 로우 레벨(raw) JSON-RPC 프로토콜 관리 대신 고수준(high-level) query() API를 사용합니다.
SSE 실시간 대시보드— WebSocket 프레임워크 의존성 없이 순수 EventSource + 바닐라 JS(vanilla JS)로 구현되었습니다.
Typed EventBus— 단순 문자열 기반의 PubSub이 아닌, 와일드카드 onAny()를 지원하는 완전한 타입 안정성(type safety)을 제공합니다.
세션별 비용 추적 (Per-session cost tracking)— 각 에이전트 세션이 USD로 정확히 얼마의 비용이 발생하는지 파악할 수 있습니다.
세밀한 도구 제어 (Fine-grained tool control)— 특정 도구를 허용하거나 차단할 수 있으며, 커스텀 canUseTool 콜백을 지원합니다.
MCP 서버 도구— 에이전트가 MCP를 통해 Linear 및 GitHub API를 직접 쿼리할 수 있습니다.
내장된 TDD— .claude/CLAUDE.md가 모든 기여에 대해 테스트 주도 개발(TDD)을 강제합니다.

# Clone
git clone https://github.com/mksglu/hatice.git
cd hatice
...

WORKFLOW.md 생성:

---
tracker:
kind: linear
...

npx tsx bin/hatice.ts start -w ./WORKFLOW.md --port 4000

tracker:
kind: github
apiKey: $GITHUB_TOKEN
...

GitLab.com과 셀프 호스팅 GitLab CE/EE 인스턴스 모두에서 작동합니다.

tracker:
kind: gitlab
endpoint: "https://gitlab.example.com" # 귀하의 GitLab 인스턴스 URL
...

severity 필드(critical/high/medium/low)가 있는 GitLab 인시던트는 자동으로 우선순위 레벨로 매핑됩니다. 두 가지가 모두 존재할 경우 우선순위 라벨(Priority::Urgent, Priority::High 등)이 우선권을 가집니다.

전체 워크플로우 예시는 examples/workflow-gitlab.md를 참조하세요.

bin/hatice.ts CLI 진입점 (Commander.js)
|
|-- StartupCleanup 오래된 워크스페이스 (stale workspaces) 제거
...

Hatice는 기본적으로 테스트 주도 개발 (Test-Driven Development, TDD) 방식을 따릅니다. TDD 방법론은 .claude/CLAUDE.md에 내장되어 있으며, 모든 기여(contribution)에 대해 강제됩니다.

# 테스트 실행
npx vitest run
# 워치 모드 (Watch mode)
...

지표 (Metric)	값 (Value)
소스 파일 (Source files)	30
...

모든 설정은 WORKFLOW.md에 정의되어 있습니다.

YAML 프론트매터 (frontmatter):

섹션 (Section)	키 (Key)	기본값 (Default)	설명 (Description)
`tracker`	`kind`	—	`linear`, `github`, `gitlab` 또는 `memory`
	`apiKey`	—	API 키 (`$ENV_VAR` 구문 지원)
	`endpoint`	`null`	트래커 API 기본 URL (GitLab의 경우 필수)
	`projectSlug`	—	프로젝트 식별자
	`activeStates`	—	디스패치 (dispatch)를 트리거하는 상태
	`terminalStates`	—	정리 (cleanup)를 트리거하는 상태
	`assignee`	`null`	담당자별 필터링 (`"me"`는 현재 사용자)
`polling`	`intervalMs`	`30000`	밀리초 단위의 폴링 (poll) 간격
`workspace`	`rootDir`	—	워크스페이스를 위한 루트 디렉토리 (`~/` 지원)
`hooks`	`afterCreate`	`null`	워크스페이스 생성 후 실행할 셸 명령 (shell command)
	`beforeRun`	`null`	에이전트 실행 전 실행할 셸 명령
	`afterRun`	`null`	에이전트 실행 후 실행할 셸 명령
	`beforeRemove`	`null`	워크스페이스 제거 전 실행할 셸 명령
	`timeoutMs`	`60000`	훅 (hook) 실행 타임아웃
`agent`	`maxConcurrentAgents`	`10`	최대 병렬 에이전트 수
	`maxTurns`	`20`	에이전트 세션당 최대 턴 (turns) 수
	`maxRetryBackoffMs`	`300000`	최대 재시도 백오프 (5분)
	`retryOnNormalExit`	`false`	성공적인 완료 후 재시도 여부
`claude`	`model`	`null`	사용할 Claude 모델
	`permissionMode`	`bypassPermissions`	SDK 권한 모드
	`turnTimeoutMs`	`3600000`	턴당 타임아웃 (1시간)
	`stallTimeoutMs`	`300000`	정체 (stall) 감지 타임아웃 (5분)
	`allowedTools`	`null`	특정 도구 화이트리스트 (whitelist)
	`disallowedTools`	`null`	특정 도구 블랙리스트 (blacklist)
	`canUseTool`	`null`

# 전체 오케스트레이터 (orchestrator) 상태 가져오기
curl http://localhost:4000/api/v1/state
# 단일 이슈 (issue) 상세 정보 가져오기
...

const es = new EventSource('http://localhost:4000/api/v1/events');
es.addEventListener('issue:dispatched', (e) => {
console.log('Dispatched:', JSON.parse(e.data));
...

import {
Orchestrator,
WorkflowStore,
...

이 프로젝트는 OpenAI의 Ryan Lopopolo가 설명한 Harness Engineering 철학과 Symphony (Elixir/OTP)에서 보여준 아키텍처 패턴에서 영감을 받았습니다.

우리는 에이전트 우선 (agent-first) 미래를 믿습니다. Hatice는 Claude Code를 통해 이를 실현하기 위한 우리의 기여입니다.

Symphony의 코드는 단 한 줄도 복사되지 않았습니다. 우리는 아키텍처를 연구하고, 선언문 (manifesto)을 채택했으며, 모든 구성 요소를 Claude Code Agent SDK를 사용하여 TypeScript로 처음부터 다시 구축했습니다. 이것은 독립적인 구현이며, 커뮤니티를 위한 선물입니다.

MIT

Claude Code Agent SDK로 제작되었습니다. 이 리포지토리의 모든 코드 라인은 인간의 안내를 받아 AI 에이전트들에 의해 작성되었습니다.

hatice: 에이전트 중심 시대를 위한 자율적 이슈 오케스트레이션

요약

핵심 포인트

hatice-01-gh.mp4

댓글