<p align="center">
<img src="https://raw.githubusercontent.com/fitlab-ai/agent-infra/HEAD/assets/logo.svg" alt="Agent Infra Logo" width="200">
</p>
<h1 align="center">Agent Infra</h1>
<p align="center">
AI 코딩 에이전트들을 위한 협업 인프라입니다 — Claude Code, Codex, Antigravity CLI, 그리고 OpenCode를 위한 기술(skills), 워크플로우, 샌드박스를 제공합니다.
</p>
<p align="center">
<strong>위험도가 선택된 라이프사이클을 거쳐 이슈에서 병합된 PR까지 관리합니다.</strong> 모든 작업은 분석으로 시작하며, 모든 구현체는 독립적인 코드 검토(code review)를 받습니다.
</p>
<p align="center">
<a href="https://www.npmjs.com/package/@fitlab-ai/agent-infra"><img src="https://img.shields.io/npm/v/@fitlab-ai/agent-infra" alt="npm version"></a>
<a href="https://www.npmjs.com/package/@fitlab-ai/agent-infra"><img src="https://img.shields.io/npm/dm/@fitlab-ai/agent-infra" alt="npm downloads"></a>
<a href="License.txt"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D22.9.0-brightgreen?logo=node.js" alt="Node.js >= 22.9.0"></a>
<a href="https://github.com/fitlab-ai/agent-infra/releases"><img src="https://img.shields.io/github/v/release/fitlab-ai/agent-infra" alt="GitHub release"></a>
<a href="https://codecov.io/gh/fitlab-ai/agent-infra"><img src="https://codecov.io/gh/fitlab-ai/agent-infra/graph/badge.svg" alt="codecov"></a>
<a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
</p>
<p align="center">
<strong>영어</strong> · <a href="./README.zh-CN.md">중국어</a>
</p>
왜 agent-infra를 사용해야 할까요?
팀들은 점점 Claude Code, Codex, Antigravity CLI, OpenCode 및 기타 AI TUI(Text User Interface)들을 같은 리포지토리에 혼합하고 있지만, 각 도구는 자체적인 명령어, 프롬프트, 로컬 관례를 도입하는 경향이 있습니다. 공유된 계층(shared layer)이 없으면, 그 결과는 파편화된 워크플로우, 중복 설정, 그리고 감사하기 어려운 작업 이력으로 이어집니다.
agent-infra는 이러한 공유 인프라를 표준화합니다. 이는 지원되는 모든 AI TUI에 동일한 작업 수명 주기(task lifecycle), 동일한 스킬 어휘집(skill vocabulary), 동일한 프로젝트 거버넌스 파일, 격리된 개발 샌드박스(development sandboxes), 그리고 동일한 업그레이드 경로를 제공하여 팀이 프로세스를 처음부터 다시 구축할 필요 없이 도구를 전환할 수 있게 합니다.
실행 예시 확인하기
<p align="center">
<img src="https://raw.githubusercontent.com/fitlab-ai/agent-infra/HEAD/assets/demo-init.gif" alt="CLI 설치 및 초기화 데모" width="720">
</p>
이 데모는 Git LFS로 저장되어 있습니다. 클론하기 전에 Git LFS를 설치하고 git lfs install을 실행하거나, 기존 체크아웃에서 git lfs pull을 실행하세요. 이미지가 작은 텍스트 포인터이거나 누락된 경우, git lfs ls-files를 확인한 후 다시 git lfs pull을 시도하세요.
초기화가 완료되면 AI TUI에서 프로젝트를 열고 최신 스킬들을 설치합니다:
AI는 .agents/.airc.json 파일을 읽어, 설치된 템플릿 루트 위치를 자동 파악하고, sync-templates.js를 통해 최신 스킬 매니페스트(skill manifests), 관리 파일 및 레지스트리를 결정론적으로 동기화합니다.
시나리오: 이슈 #42는 "로그인 API가 이메일에 플러스 기호(+)가 포함된 경우 500을 반환합니다"라는 내용을 보고합니다. 모든 작업은 분석(analysis)으로 시작하며, 이는 관찰 가능한 사실들로부터 하나의 정규 경로를 기록합니다:
| 경로 | 단계 | 사용 시점 |
|---|
| Streamlined | analyze → code → review-code | 범위와 수용 기준이 명확하고 별도의 설계 또는 문서 감사 결정이 필요하지 않을 때 |
| ... | | |
파일 개수, 모듈 개수, 또는 단순히 가능한 위험만으로는 전체 경로가 선택되지 않습니다. 나중에 발견된 사항은 새로운 증거가 정당화될 경우 작업 흐름을 분석(analysis), 계획(planning), 또는 코드(code)로 되돌릴 수 있으며, 독립적인 review-code는 모든 경로의 일부로 남아 있습니다. | | |
애플리케이션 계층 경계에 명시적인 계획이 필요한 경우, 분석 단계가 **표준 경로(standard path)**를 선택한다고 가정해 봅시다:
/import-issue 42
/analyze-task --task <task-id>
/plan-task --task <task-id>
사용자가 계획을 검토하고 자연어로 응답합니다:
The plan looks right, but don't change the DB schema.
Just fix it at the application layer in LoginService.
AI는 이에 맞춰 계획을 업데이트하기 위해 /plan-task를 재실행하고 확인합니다.
/code-task --task <task-id>
/review-code --task <task-id>
/code-task --task <task-id>
...
분석을 통해 선택된 경로 하나, 자연어 수정 한 번, 그리고 독립적인 코드 리뷰가 이루어집니다. 이 라이프사이클은 증거와 검토 깊이를 태스크에 비례하게 유지합니다.
위의 모든 명령어는 Claude Code, Codex, Antigravity CLI, 그리고 OpenCode에서 동일하게 작동합니다. 작업 도중 도구를 전환해도 워크플로우 상태가 유지됩니다. 각 스킬이 내부적으로 어떤 작업을 수행하는지는 Built-in AI Skills를 참조하세요.
주요 기능 (Key Features)
- 다중 AI 협업(Multi-AI collaboration): Claude Code, Codex, Antigravity CLI, OpenCode를 위한 단일 공유 운영 모델
- Bootstrap CLI + 스킬 기반 실행(skill-driven execution): 한 번 초기화하고, 이후 AI 스킬이 일상 작업을 주도하도록 합니다
- IM 명령어 브릿지(IM command bridge): Feishu 메시지를 내장 기능(built-ins), 읽기 전용 작업 보기, 샌드박스 관리 및 제어된 라이프사이클 스킬 실행으로 라우팅합니다
- 이중 언어 프로젝트 문서(Bilingual project docs): 영어 우선 문서를 중국어 번역과 동기화하여 제공합니다
- 템플릿 소스 아키텍처(Template-source architecture):
templates/ 디렉토리가 렌더링된 프로젝트 구조를 반영합니다
- AI 지원 업데이트(AI-assisted updates): 프로젝트별 사용자 정의 설정을 유지하면서 템플릿 변경 사항을 병합할 수 있습니다
- 감사 가능한 프로세스 데이터 아카이브(Auditable process-data archive): 로컬 작업 및 GitHub 증거를 추가 전용(append-only), 검증 가능한 스냅샷으로 보존합니다
샌드박스 제어 경계 (Sandbox control boundary)
Direct-host 라이프사이클 및 워크플로우 명령어는 현재 CLI 프로세스에서 실행됩니다. 작업에 바인딩된(Task-bound) 샌드박스는 요청을 브로커로 라우팅하며, 브로커는 단일 요청 실행기(one-request executor)를 시작하기 전에 요청, 매니페스트(manifest), 생성(generation), 소유자(owner), 임대(lease), 컨트롤러를 검증합니다. 호스트 소켓(host socket), 워커 토큰(worker token) 또는 사용자 수준 작업 제어 서비스는 없습니다.
작업에 바인딩된 샌드박스 내부에서 노출되는 작업 디렉토리는 해당 작업에 대해서만 쓰기가 가능합니다. Artifact 명령어는 유형화된 워크플로우 연산 및 표준 아티팩트 기본 이름(canonical artifact basenames)을 받습니다. 실행기는 O_NOFOLLOW로 후보 파일을 열고, 하나의 파일 디스크립터를 통해 읽고 해시하며, 관찰 가능한 메타데이터 변경 사항을 확인한 후, 검증된 바이트를 권위 있는 작업 디렉토리에 원자적으로 저장합니다.
빠른 시작 (Quick Start)
1. agent-infra 설치
옵션 A - npm (권장)
npm install -g @fitlab-ai/agent-infra
옵션 B - 셸 스크립트(Shell script)
curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh
옵션 C - Homebrew (macOS)
새로운 Homebrew는 신뢰되지 않은 타프(tap)의 포뮬러를 로드하는 것을 거부하며, 이는 업그레이드를 조용히 차단합니다. 설치하기 전에 해당 타프를 한 번 신뢰하십시오.
brew trust fitlab-ai/tap
...
agent-infra 업데이트하기
ai update는 설치된 agent-infra CLI를 업데이트합니다. 프로젝트가 초기화된 경우, ai sync를 사용하여 프로젝트 시드 파일과 파일 레지스트리를 새로 고치십시오.
동일한 패키지 관리자 명령어도 유효합니다:
npm update -g @fitlab-ai/agent-infra
brew upgrade agent-infra
현재 버전을 확인하십시오:
2. 새 프로젝트 초기화하기
CLI는 프로젝트 메타데이터를 수집하고, 활성화할 에이전트 클라이언트(Agent Clients)를 선택하게 하며, 클라이언트별 update-agent-infra 시드 명령어를 설치하고, .agents/.airc.json 파일을 생성합니다.
ai는 agent-infra의 약어입니다. 두 명령어 모두 동일한 기능을 수행합니다.
3. 전체 인프라 렌더링하기
모든 AI TUI에서 프로젝트를 열고 update-agent-infra를 실행하십시오:
| TUI | 명령 |
|---|
| Claude Code | /update-agent-infra |
| ... | |
이 명령어는 패키징된 템플릿 버전을 감지하고 관리되는 모든 파일을 렌더링합니다. 이 명령어는 최초 설정과 향후 템플릿 업그레이드 모두에 사용됩니다.
핵심 명령어 (Core Commands)
프로젝트 수명 주기와 독립적으로 다섯 가지 내장 에이전트 클라이언트(Agent Clients)를 관리할 수 있습니다:
ai agent-client list
ai agent-client status
ai agent-client enable codex
...
가장 많이 사용되는 수명 주기 명령어들을 전달 순서대로 나열했습니다. 명령어 접두사는 TUI별로 다릅니다 (Claude Code/Antigravity/OpenCode/TraeCode에서는 /skill, Codex에서는 $skill을 사용). 하지만 워크플로우 의미론(workflow semantics)은 동일하게 유지됩니다.
| 명령어 | 목적 |
|---|
create-task / import-issue | 설명 또는 GitHub Issue에서 작업을 시작합니다 |
| ... | |
전체 카탈로그 — 작업 상태, 릴리스, 보안 및 프로젝트 관리 스킬(skills) — 은 Built-in AI Skills를 참조하십시오.
얻게 되는 것 (What You Get)
설정 후, 프로젝트는 완벽한 AI 협업 인프라를 갖추게 됩니다:
my-project/
├── .agents/ # 공유 AI 협업 설정
│ ├── .airc.json # 중앙 설정 파일
...
문서화 (Documentation)
심층 가이드는 docs/en/에서 확인할 수 있습니다:
- 프로세스 데이터 아카이브 — 캡처, 검증, 감사, 복구, 내보내기, 개인 정보 보호 및 백업 가이드
- 아키텍처 개요 — 부트스트랩 CLI, 엔드투엔드 흐름, 계층형 아키텍처
- 플랫폼 지원 — macOS, Linux, Windows; 샌드박스 엔진 및 리소스
- 샌드박스 — 샌드박스 별칭, 호스트-샌드박스 파일 교환, 사용자 레벨 dotfiles 채널
- 벤치마크 계약 및 위협 모델 — 버전 관리되는 벤치마크 스키마, 신뢰 경계, 보안 보장
- Feishu 브릿지 — Feishu 장기 연결 어댑터, 명령어 라우팅, 권한 및 TUI 선택 구성
- 내장 AI 기능 — 사용 사례별 전체 스킬 카탈로그
- 사용자 정의 스킬 — 프로젝트별 스킬 생성 및 동기화
- 사용자 정의 도구 호출 — 사용자 정의 도구 다음 단계 명령어 구성
- 사전 구축 워크플로우 — 게이티드 배포 라이프사이클 및 예시 흐름
- 설정 참조 — .agents/.airc.json, 외부 소스, 버전 관리
- 파일 관리 전략 — 관리 / 병합 / 제거 업데이트 전략
기여 (Contributing)
개발 지침은 CONTRIBUTING.md를 참조하십시오.
라이선스 (License)
MIT
