nrslib/takt

📦 프로젝트: TAKT – AI 에이전트 조정 CLI

개요

• Node‑JS 기반 명령줄 도구로, 간단한 YAML 설명을 사용하여 AI 코딩 에이전트(Claude, OpenAI Codex, DeepSeek, Cursor, GitHub Copilot 등)를 위한 반복 가능한 개발 워크플로우를 정의할 수 있습니다.
• CLI는 각 단계를 격리된 Git 작업 트리에서 실행하고, 모든 것을 기록하며, 워크플로우가 끝나면 자동으로 PR을 열 수 있습니다.

중요성

• AI 에이전트는 이전 지시를 잊거나, 구현과 검토를 혼합하고, 감사할 수 없는 변경을 생성하는 경향이 있습니다. TAKT는 프로세스를 모델의 프롬프트에서 꺼내 CLI가 강제하는 선언적 워크플로우로 옮깁니다.
• 각 단계는 고유한 페르소나, 권한, 지식, 출력 계약을 가지므로 모델은 필요한 컨텍스트만 볼 수 있습니다.
• 검토/수정 루프, 인간 체크포인트, 단계별 출력 검증을 기본 지원합니다.

핵심 개념

개념	역할
워크플로우	단계의 순서 목록(계획 → 구현 → 검토 → 수정 …). workflows/*.yaml에 정의됩니다.
단계	특정 페르소나, 권한, 규칙을 가진 하나의 에이전트 실행으로 다음 단계를 결정합니다.
제공자	기본 AI 서비스(Claude SDK, Codex SDK, OpenCode CLI 등). TAKT는 SDK 또는 외부 CLI를 통해 제공자와 통신합니다.
격리된 작업 트리	에이전트가 변경하는 임시 Git 체크아웃으로, 메인 저장소를 깨끗하게 유지합니다.
로그 및 보고서	각 단계 후 TAKT는 상세 로그와 요약 보고서를 작성하여 작업에서 PR까지의 경로를 감사 가능하게 만듭니다.

주요 기능

• YAML 기반 워크플로우 – 페르소나, 권한, 전환 규칙을 선언합니다.
• 다중 제공자 – Claude, Codex, OpenCode, DeepSeek Harness, Cursor, Copilot, Kiro 등.
• 자동 SDK 설치 (takt install <provider>) 및 업데이트.
• 검토 루프 – 명시적 수정 및 재검토 주기, 선택적 인간 승인.
• 작업 큐 – takt add로 작업 생성, takt run으로 실행, takt watch로 상주 실행기.
• 웹 UI – 선택적 뷰어 우선 UI (http://127.0.0.1:20525)로 실시간 로그 및 보고서 제공.
• 통합 훅 – 다른 도구를 위한 Agent Client Protocol (ACP) 또는 MCP 서버로 사용 가능.
• 내장 워크플로우 – default, maintenance, pure, review 등과 페르소나 카탈로그.
• 정형 검증 지원 – 선택적 Quint/Alloy 사양 검사.

일반적인 워크플로우

1. takt (또는 takt exec)로 AI와 대화하여 작업을 설명합니다.
2. /go를 사용하여 워크플로우 YAML을 생성하고 작업으로 저장합니다.
3. takt run 실행 – TAKT가 격리된 작업 트리를 만들고, 각 단계를 실행하고, 결과를 기록하고, PR 열기를 제안합니다.
4. takt list, takt merge, takt retry 등으로 작업을 관리합니다.

설치 및 빠른 시작

# 전역 설치 (Node ≥22.22 필요)
npm install -g takt
# 제공자 SDK 설치 (예: Claude)
takt install claude-sdk

# 저장소 초기화 (최소 하나의 커밋 필요)
takt   # AI와 대화 후 /go → 작업으로 저장

takt run   # 대기 중인 작업 실행

Nix로도 설치할 수 있습니다:

nix run github:nrslib/takt
nix profile install github:nrslib/takt

사용 사례

• 자동화된 기능 개발 – 수동 PR 변경 없이 새 기능을 계획, 코딩, 검토, 수정합니다.
• 버그 분류 – GitHub 이슈를 작업으로 전환하고, AI가 수정을 제안하고, 검토 루프를 실행하고, 자동 병합합니다.
• 팀 수준 오케스트레이션 – 여러 에이전트 간 작업을 분해하는 팀 전체 워크플로우(takt-default-team)를 정의합니다.
• 정형 검증 – 병합 전에 생성된 코드를 검증하기 위해 Quint 사양을 연결합니다.

제한 사항 / 고려 사항

• Node 22+ 및 적절한 제공자 SDK 또는 외부 CLI가 설치되어 있어야 합니다.
• 결과 품질은 기본 AI 모델에 따라 달라지며, 복잡한 도메인은 여전히 인간의 감독이 필요할 수 있습니다.
• 검토 루프는 명시적이지만 모델이 계약을 충족하지 못하면 길어질 수 있습니다.
• 일부 제공자는 추가 시스템 종속성이 필요합니다 (예: claude-terminal용 tmux, Quint 검증용 Java 17).
• 기본 웹 UI는 실험적이며 현재 일본어 우선입니다.

더 알아보기

• 전체 문서: docs/README.md (영어) 및 docs/의 번역.
• 비디오 튜토리얼: README에 링크된 1장 및 2장.
• CLI 참조: docs/cli-reference.md.
• 워크플로우 가이드 및 내장 카탈로그: docs/workflows.md 및 docs/builtin-catalog.md.

---

TAKT는 자체적으로 TAKT로 구축되어(도그푸딩) 도구의 자체 호스팅 특성을 보여줍니다.