Agentic Software Factory
사용자가 이미 사용하고 있는 코딩 에이전트를 활용하여 목표(objective)나 GitHub Issue를 계획되고, 검토되며, 통합 가능한 소프트웨어 워크플로우로 변환하는 로컬 멀티-에이전트 소프트웨어 엔지니어링 런타임입니다.
Factory는 모델을 제공하지 않습니다. 에이전트를 오케스트레이션(orchestrates)합니다.
사용자는 코딩 CLI(Codex, Claude Code, OpenCode, Gemini CLI, Qwen Code 또는 자체 개발한 것)를 설치하고, Factory가 작업을 실제 태스크 DAG로 계획하며, 격리된 Git worktree에서 작업을 실행하고, 증거를 검토하며, 승인된 작업을 개별 실행 브랜치에 통합하고, 이를 풀 리퀘스트(pull request) 형태로 전달할 수 있습니다. 모든 상태는 사용자의 기기에 유지됩니다.
Factory Agent Graph
Objective / GitHub Issue
↓
Planner
...
Factory를 사용하는 이유 (Why Factory)
-
여러 독립적인 코딩 에이전트 조정: 에이전트는 역할을 공유하며, Factory는 어떤 에이전트가 각 디스패치(dispatch)를 처리할지 결정하고 모든 호출을 기록합니다.
-
목표를 의존성 인식 계획으로 변환: Planner는 실행되기 전에 검사할 수 있는 태스크 DAG를 생성합니다.
-
Git worktree에서 구현 격리: 모든 작업은 자체 브랜치에서 작동하며, 승인된 작업은 factory/run-<id>에 통합됩니다. 메인 브랜치는 절대 건드려지지 않습니다.
-
통합 전 검토: 태스크는 구조화된 Reviewer의 승인이 있어야만 완료되며, 전문적인 검토를 통해 request_changes가 경계가 있는 재작업(rework)으로 라우팅될 수 있습니다.
-
지속 가능한 워크플로우 상태 보존: 실행(Runs), 태스크(tasks), 시도(attempts), 세션(sessions), 증거(evidence), 아티팩트(artifacts), 계획 수정본은 로컬 SQLite에 존재하며 재시작 후에도 유지됩니다.
-
에이전트 성능에 따른 작업 라우팅: 선택적 결정론적 라우팅(deterministic routing)을 통해 측정된 로컬 이력을 바탕으로 적격한 에이전트를 순위별로 지정합니다.
-
역할/정책 경계 강제: 역할은 에이전트가 무엇을 해야 하는지 말하고, 정책은 무엇을 할 수 있는지 허용하는지를 말합니다. 거부(Deny)가 승리하며, Factory의 안전 불변성(safety invariants)이 항상 적용됩니다.
-
기록 재작성 없이 미완료 작업 재계획: 계획 변경 사항은 지속 가능한 수정본으로 저장되며, 완료된 태스크는 절대 조용히 덮어쓰여지지 않습니다.
-
GitHub Issue를 pull request에 연결합니다. Issue를 가져와(import), 일반 파이프라인을 실행하고, 로컬 인증된 gh CLI를 통해 완료된 실행 결과를 PR로 전달할 수 있습니다.
-
제어된 MCP 도구 노출. 외부 도구는 정책 기반의 범위가 지정된 권한(policy-mediated, scoped grants)을 통해서만 작업 에이전트에 접근할 수 있으며, 그 결과물은 신뢰되지 않은 데이터로 유지됩니다.
간단한 워크플로우는 간단하게 유지됩니다. 작은 수정이라도 여전히 Worker → Reviewer 순서로 계획을 세웁니다.
작동 방식
Agent Graph → local API → Factory Core → Planner → task DAG
→ task worktrees → evidence
→ Reviewer → approve or retry
...
- Plan은 저장소를 변경하지 않고 선택된 Planner에게 구조화된 작업과 의존성을 요청합니다. 작업은 워크플로우 팀의 특정 역할을 대상으로 할 수 있습니다.
- Start는 팀, Git 저장소, DAG, 그리고 각 작업의 유효 정책을 검증한 다음, 준비된 작업을 격리된 worktree에서 하나씩 실행합니다.
- 모든 작업은 역할과 연산에 의해 배포됩니다. 각 시도는 역할, 에이전트, 적용된 정책을 기록하는
AgentSession입니다.
- 프로세스 종료가 완료를 의미하지는 않습니다. 작업은 구조화된 Reviewer의 승인이 있어야만 완료됩니다. Worker 실패 및 변경 요청은 최대 세 번까지 재시도할 수 있으며, 정책 차단(policy blocks)은 절대 재시도를 소모하지 않습니다.
- 승인된 작업은 통합됩니다. Integration Engine은 승인된 구현 계열(implementation-family) 작업을 실행의
factory/run-<id> 브랜치에 배치하며, 완료된 실행은 pull request로 전달될 수 있습니다.
Rust Factory 프로세스가 실행을 담당합니다. 브라우저를 닫는 것이 활성 작업을 중단시키지 않습니다. 모든 상태는 .factory/에 저장됩니다:
.factory/
db.sqlite3 workflows, tasks, attempts, sessions, artifacts, and audit
config.toml agents, role assignments, policies, and MCP servers
...
핵심 기능
| 기능 (Capability) | 설명 (What it does) | 참고 자료 (Reference) |
|---|
| Role-aware multi-agent workflows | 기본 8가지 역할과 사용자 정의 역할을 포함하며, 모든 작업은 해당 역할의 실행 클래스를 기반으로 검증된 역할 및 의미론적 연산을 가집니다. | Roles |
| ... | | |
설치 (Install)
미리 만들어진 바이너리가 Windows (x86_64), Linux (x86_64), 그리고 macOS (Apple Silicon 및 Intel)용으로 제공됩니다. Rust, Node 또는 관리자 권한이 필요하지 않습니다.
Windows
imr https://raw.githubusercontent.com/OmegaMc1331/agentic-software-factory/main/install.ps1 | iex
Linux / macOS
curl -fsSL https://raw.githubusercontent.com/OmegaMc1331/agentic-software-factory/main/install.sh | sh
그런 다음 설치를 확인합니다:
설치 프로그램은 HTTPS를 통해 릴리스 아카이브를 다운로드하고 게시된 SHA-256 체크섬을 검증합니다. factory가 발견되지 않으면 새 터미널을 열어야 합니다: Windows는 설치 위치를 사용자 PATH에 추가하며, macOS와 Linux는 셸 프로필에 추가할 줄을 출력합니다. 설치 프로그램을 다시 실행하면 이전 버전을 최신 릴리스로 대체합니다.
제거 (Uninstall) — 바이너리와 추가한 모든 PATH 항목을 제거하십시오:
- Windows:
%LOCALAPPDATA% extbackslash Programs extbackslash AgenticSoftwareFactory를 삭제한 다음, **시스템 속성 → 환경 변수(System Properties → Environment Variables)**에서 사용자 PATH에 있는 bin 디렉토리를 제거합니다.
- macOS / Linux:
rm ~/.local/bin/factory.
프로젝트 로컬의 .factory/ 상태는 제거되지 않습니다.
빠른 시작 (Quick start)
cd my-project
factory init
factory start
factory init은 시작 구성(starter configuration)을 가진 .factory/를 생성합니다: 예시 에이전트 엔트리(Codex, OpenCode, Claude Code), 파이프라인 역할 할당, 그리고 핵심 역할을 위한 정책 프리셋입니다. factory start는 로컬 API와 대시보드를 제공하고, 서버가 준비될 때까지 기다린 후 http://127.0.0.1:4321을 엽니다.
에이전트 그래프에서 (In Agent Graph):
- 코딩 에이전트를 설정하고 인증합니다. Factory는 모델 제공업체와 직접 통신하지 않으며, 각 CLI가 자체적인 인증을 유지합니다.
- Planner, Worker, Reviewer를 할당합니다. 새로운 구성에서는 세 가지 파이프라인 역할이 이미 모두 할당됩니다. 실제로 보유한 에이전트에 맞게 조정하십시오.
- 목표로부터 워크플로우를 생성하거나 GitHub Issue를 가져옵니다.
- 생성된 계획을 검사합니다 — 작업, 종속성, 역할 및 운영(operations) — 그리고 시작하기 전에 팀을 편집합니다.
- 워크플로우를 시작합니다.
- 워크플로우 인스펙터(Workflow Inspector)와 성능 뷰(Performance view)에서 실행 내역 — 시도(attempts), 증거(evidence), 검토(reviews), 아티팩트(artifacts), 그리고 통합 브랜치(integration branch) — 를 검사합니다.
- 완료된 실행으로부터 풀 리퀘스트(pull request)를 선택적으로 생성할 수 있습니다.
에이전트와 역할 (Agents and roles)
의도적으로 분리된 세 가지 개념입니다:
Agent = 설치하고 인증하는 실행 가능한 코딩 CLI(CLI)
Role = Factory 내부의 책임(responsibility)
Assignment = 에이전트가 역할을 수행할 수 있는 권한(permission)
Codex Claude
├─ Planner ├─ Reviewer
├─ Worker └─ Security Auditor
...
역할은 여러 에이전트에 의해 채워질 수 있으며, 하나의 에이전트는 여러 역할을 가질 수 있습니다. worker2-스타일의 중복 할당은 불가능합니다. 역할은 에이전트 독립적입니다: 어떤 에이전트가 역할을 실행하든, 책임(responsibility), 운영 의미론(operation semantics), 그리고 정책은 동일하게 유지됩니다.
예시 워크플로우 (Example workflow)
목표: "공개 API 엔드포인트에 속도 제한(rate limiting)을 추가합니다."
Planner가 DAG를 생성합니다
1. Architect advisory 속도 제한 설계, 제약 조건 → artifact
2. Worker implement 미들웨어 + 구성 (필요 1) → evidence
...
- 작업 2는
.factory/worktrees/t2에서 실행되며, 종속성(dependency)의 Architect 아티팩트를 사용하고, 수용 기준(acceptance criteria)에 따라 검토됩니다.
- 작업 3은 이미 통합된 헤드(head)를 기반으로 워크트리(worktree)를 구성하므로, 작업 2가 실제로 무엇을 변경했는지 테스트합니다.
- 실행이 완료되면, Pull Request 생성(Create Pull Request) 기능이
factory/run-7을 푸시하고 기록된 증거(recorded evidence)로부터 본문(body)이 생성된 PR을 엽니다. (절대 임의로 작성되지 않음).
보안 및 신뢰 모델 (Security and trust model)
- Factory는 로컬 우선(local-first) 방식입니다: 상태는
.factory/에 존재하며, 외부 서비스로는 아무것도 전송되지 않습니다.
- API는 **
127.0.0.1에 바인딩(binds)**되며, 호스트/오리진 검사(Host/Origin checks) 및 CSRF 보호 기능을 갖춘 단기 세션의 동일 출처 브라우저 세션을 요구합니다. 여전히 로컬 신뢰 경계이므로 프록시하거나 노출해서는 안 됩니다.
- 작업 워크트리는 OS 샌드박싱(sandboxing)이 아닌 Git 격리(isolation) 방식입니다.
- 외부 코딩 에이전트는 Factory를 시작한 사용자의 OS 권한을 유지합니다.
- **정책 엔진(Policy Engine)**은 오케스트레이션 수준의 제어(파일 시스템 범위(filesystem scopes), 명령어 허용/거부(command allow/deny), 환경 필터링(environment filtering), Git 제한(Git limits))를 제공하며, 이는 Factory 경계와 기록된 증거에 대해 강제됩니다. 프로세스 샌드박스가 아닙니다.
- 네트워크 제한은 OS 수준에서 강제되지 않을 수 있습니다. 네트워크 정책은 모든 현재 플랫폼에서 자문(advisory) 사항입니다.
- MCP 결과 및 GitHub 이슈 내용은 신뢰할 수 없는 데이터로 취급되며, 역할, 권한 또는 출력 계약(output contract)을 절대 변경할 수 없습니다.
신뢰하는 에이전트를 실행하세요. 전체 모델은 docs/security.md를 참조하십시오.
보안 취약점을 보고하려면 SECURITY.md를 따르십시오. 공용 이슈에 취약점 세부 정보를 게시하지 마십시오.
문서화 (Documentation)
개발 (Development)
소스 빌드(source builds), 테스트, 그리고 임베디드 대시보드 릴리스 빌드에 대한 내용은 docs/development.md를 참조하고, 기여 원칙(contribution principles)은 CONTRIBUTING.md를 참조하십시오. 품질 게이트(Quality gates):
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cd apps/dashboard
npm ci && npm run format:check && npm run lint && npm run typecheck && npm test && npm run build
라이선스 (License)
MIT. 자세한 내용은 LICENSE를 참조하십시오.
