Hatice: Harness Engineering 실현 — OpenAI Symphony를 TypeScript로 재구현

“Humans steer. Agents execute.”

이 문장이 Hatice의 철학을 관통합니다. OpenAI의 Symphony에서 영감을 받아, Claude Code Agent SDK를 기반으로 TypeScript로 재구현한 자율 코딩 에이전트 오케스트레이션 시스템입니다.

2026년 3월 6일, mksglu (Mert Can Altın)에 의해 탄생했습니다. 매우 최신 프로젝트이지만, 이미 30개 소스 파일, 328개 테스트, 10,817줄의 코드를 갖춘 완성도 높은 시스템입니다.

탄생 배경: Harness Engineering 선언문

Hatice는 단순한 이슈 자동화 도구가 아닙니다. Harness Engineering이라는 철학을 실현하는 시스템입니다.

엔지니어의 새로운 역할

“Humans steer. Agents execute.” — Hatice의 핵심 철학

모든 코드는 에이전트가 작성합니다. 인간은 방향을 잡고, 환경을 설정하고, 결과를 검증합니다.

Symphony vs Hatice: 두 오케스트레이터의 대결

OpenAI의 Symphony에서 영감을 받았지만, Hatice는 TypeScript 생태계에 맞게 완전히 재설계되었습니다.

Hatice만의 독자적 기능

1. GitHub Issues 지원 — owner/repo 형식으로 GitHub 이슈도 폴링
2. Claude Code Agent SDK — 고수준 query() API로 간결한 에이전트 제어
3. SSE 실시간 대시보드 — HTTP 서버로 실시간 상태 모니터링
4. 타입드 EventBus — 와일드카드 지원으로 유연한 이벤트 핸들링
5. 세션별 비용 추적 — 각 에이전트 세션의 USD 비용 추적
6. 세밀한 도구 제어 — allowedTools / disallowedTools로 권한 관리
7. MCP 서버 도구 — Linear/GitHub GraphQL 도구 직접 사용
8. 내장 TDD 아키텍처 — .claude/CLAUDE.md에 TDD 방법론 내장

아키텍처: 7개 컴포넌트의 조화

bin/hatice.ts CLI 진입점
    |
    |-- StartupCleanup (오래된 워크스페이스 정리)
    |-- Supervisor (충돌 복구)
    |
    v
Orchestrator (메인 상태 머신)
    |-- OrchestratorState (running/claimed/completed/retry)
    |-- WorkflowStore (WORKFLOW.md 핫 리로드)
    |-- Workspace (격리 디렉토리 + 훅 + 정리)
    |
    |-- AgentRunner (Claude SDK 턴 루프)
    |   |-- SessionLogger (세션별 로그)
    |   |-- RateLimiter (429 추적)
    |   |-- InputHandler (입력 자동 응답)
    |   |-- TurnTimeout (턴별 마감)
    |   '-- PromptBuilder (LiquidJS 템플릿)
    |
    |-- EventBus (11개 이벤트 타입)
    |
    v
HttpServer (Hono)
    |-- GET / (SSE 대시보드)
    |-- GET /api/v1/state
    |-- GET /api/v1/:id
    |-- GET /api/v1/events
    '-- POST /api/v1/refresh

핵심 컴포넌트 분석

Orchestrator — 메인 상태 머신

• running: 이슈 폴링 중
• claimed: 에이전트가 작업 중
• completed: 작업 완료
• retry: 실패 시 재시도

WorkflowStore — WORKFLOW.md 핫 리로드

• YAML frontmatter로 설정
• LiquidJS 템플릿으로 프롬프트 구성
• 파일 변경 시 자동 리로드

Workspace — 격리 디렉토리

• 각 이슈별 독립 워크스페이스
• 훅 시스템 (pre/post)
• 자동 정리

AgentRunner — Claude SDK 턴 루프

• 세션별 로그
• 429 Rate Limit 추적
• 입력 자동 응답
• 턴별 타임아웃

EventBus — 타입드 이벤트

• 11개 이벤트 타입
• 와일드카드 구독 지원
• 타입 안전성

WORKFLOW.md: 선언적 오케스트레이션 설정

---
tracker:
  kind: linear
  apiKey: $LINEAR_API_KEY
  projectSlug: "MY-PROJECT"
  activeStates: ["Todo", "In Progress"]
  terminalStates: ["Done", "Cancelled"]
  assignee: "me"

workspace:
  rootDir: ~/workspaces

agent:
  maxConcurrentAgents: 5
  maxTurns: 20
  claude:
    permissionMode: bypassPermissions

server:
  port: 4000
---

You are an expert software engineer.
Solve the following issue:

**{{ issue.identifier }}: {{ issue.title }}**

{{ issue.description }}

Work in the provided workspace.
Write tests first, then implement.
Commit when done.

GitHub Issues 설정

tracker:
  kind: github
  apiKey: $GITHUB_TOKEN
  projectSlug: "owner/repo"
  activeStates: ["open"]
  terminalStates: ["closed"]

owner/repo 형식만으로 GitHub Issues를 폴링할 수 있습니다.

설치 및 실행

설치

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

# 설치
npm install

데모 모드 (API 키 불필요)

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

HTTP 서버 모드

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

API 엔드포인트

SSE 이벤트 구독

const es = new EventSource('http://localhost:4000/api/v1/events');

es.addEventListener('issue:dispatched', (e) => {
  console.log('이슈 디스패치됨:', e.data);
});

es.addEventListener('issue:completed', (e) => {
  console.log('이슈 완료:', e.data);
});

es.addEventListener('state:updated', () => {
  fetch('/api/v1/state')
    .then(r => r.json())
    .then(console.log);
});

11개 이벤트 타입

Hatice의 EventBus는 11개의 타입드 이벤트를 발생시킵니다:

테스트

# 테스트 실행
npx vitest run

# watch 모드
npx vitest

# 타입 체크
npx tsc --noEmit

# 빌드
npx tsup

코드 통계

테스트 라인이 소스 라인보다 많습니다. TDD가 내장된 시스템답게, 테스트 커버리지가 매우 높습니다.

MCP 도구: Linear & GitHub GraphQL

Hatice는 MCP (Model Context Protocol) 서버를 통해 Linear와 GitHub의 GraphQL API에 직접 접근합니다.

linear_graphql

// Linear GraphQL 쿼리 실행
await useMcpTool("linear_graphql", {
  query: `
    query Issues($filter: IssueFilter) {
      issues(filter: $filter) {
        nodes {
          id
          identifier
          title
          description
        }
      }
    }
  `,
  variables: {
    filter: {
      project: { slug: { eq: "MY-PROJECT" } },
      state: { name: { in: ["Todo", "In Progress"] } }
    }
  }
});

github_graphql

// GitHub GraphQL 쿼리 실행
await useMcpTool("github_graphql", {
  query: `
    query($owner: String!, $repo: String!) {
      repository(owner: $owner, name: $repo) {
        issues(first: 100, states: [OPEN]) {
          nodes {
            number
            title
            body
          }
        }
      }
    }
  `,
  variables: {
    owner: "owner",
    repo: "repo"
  }
});

세션별 비용 추적

Hatice는 각 에이전트 세션의 비용을 추적합니다.

interface SessionCost {
  sessionId: string;
  inputTokens: number;
  outputTokens: number;
  costUSD: number;
  duration: number;
}

이를 통해 어떤 이슈가 가장 많은 비용을 소비했는지, 평균 해결 비용은 얼마인지 분석할 수 있습니다.

세밀한 도구 제어

에이전트가 사용할 수 있는 도구를 제한할 수 있습니다.

agent:
  allowedTools:
    - read_file
    - write_to_file
    - list_directory
    - search_files
  disallowedTools:
    - execute_command
    - delete_path

이를 통해 파괴적 명령을 방지하고, 안전한 샌드박스 환경을 구축할 수 있습니다.

내장 TDD 아키텍처

.claude/CLAUDE.md에 TDD 방법론이 내장되어 있습니다.

# Hatice TDD Workflow

## Phase 1: Red
1. Write a failing test first
2. Run the test to confirm it fails
3. Commit the failing test

## Phase 2: Green
1. Write the minimum code to pass
2. Run the test to confirm it passes
3. Commit the passing code

## Phase 3: Refactor
1. Refactor while keeping tests green
2. Run tests after each change
3. Commit the refactored code

에이전트는 자동으로 Red-Green-Refactor 사이클을 따릅니다.

실제 사용 시나리오

시나리오 1: 스타트업 백로그 자동 해결

설정:

• Linear 프로젝트: “STARTUP-PROJECT”
• 활성 상태: “Todo”, “In Progress”
• 최대 동시 에이전트: 3

워크플로우:

1. Linear에서 “Todo” 이슈 폴링
2. 각 이슈를 격리된 워크스페이스에 디스패치
3. Claude Code 에이전트가 TDD로 구현
4. 완료 시 “Done”으로 상태 변경
5. SSE로 실시간 진행 상황 모니터링

시나리오 2: 오픈소스 이슈 트리아주

설정:

• GitHub: “owner/oss-project”
• 활성 상태: “open”

워크플로우:

1. GitHub Issues에서 “open” 이슈 폴링
2. 버그 리포트 → 재현 → 수정 → PR 생성
3. 기능 요청 → 설계 → 구현 → PR 생성
4. 비용 추적으로 ROI 분석

시나리오 3: 엔터프라이즈 QA 자동화

설정:

• Linear 프로젝트: “QA-AUTOMATION”
• 턴 제한: 50
• 허용 도구: 테스트 관련만

워크플로우:

1. QA 이슈 폴링
2. E2E 테스트 작성
3. 실행 및 결과 보고
4. 실패 시 재시도

Symphony에서 Hatice로: 마이그레이션 가이드

Elixir/OTP → TypeScript/Node.js

Codex → Claude Code

Phoenix LiveView → Hono SSE

로드맵

• GitLab Issues 지원
• Jira 지원
• 멀티 리포지토리 오케스트레이션
• 에이전트 협업 (A가 작업 → B가 리뷰)
• 비용 예산 설정
• Slack/Discord 알림
• 웹 대시보드 UI

마치며: Humans Steer, Agents Execute

Hatice는 단순한 자동화 도구가 아닙니다. Harness Engineering 철학을 실현하는 플랫폼입니다.

OpenAI Symphony에서 영감을 받았지만, TypeScript 생태계에 맞게 완전히 재설계했습니다. Claude Code Agent SDK, Hono SSE, MCP 도구, 내장 TDD — 모든 것이 TypeScript 네이티브입니다.

특히 인상적인 것은 테스트 커버리지입니다. 328개 테스트, 테스트 라인이 소스 라인보다 많습니다. TDD가 내장된 시스템답게, 프로덕션 준비도가 매우 높습니다.

GitHub Issues 지원도 독특합니다. owner/repo 형식만으로 오픈소스 프로젝트의 이슈를 자동으로 해결할 수 있습니다.

여러 이슈를 동시에 처리하고 싶다면, Hatice를 시도해보세요. 인간은 조종하고, 에이전트는 실행합니다.

🔗 관련 정보

• GitHub: https://github.com/mksglu/hatice
• 개발자: mksglu (Mert Can Altın)
• 생성일: 2026년 3월 6일
• 언어: TypeScript
• 런타임: Node.js 20+ / Bun
• 영감: OpenAI Symphony
• 기반: Claude Code Agent SDK
• 철학: Harness Engineering 선언문