aniketkarne/aco-system

자율적 또는 반자율적으로 작동하는 멀티 에이전트 소프트웨어 개발 팀을 위한 프레임워크입니다. 6개의 특화된 에이전트가 공유 데이터베이스 파이프라인을 통해 협업합니다: 요구사항 (requirements) → 계획 (planning) → 아키텍처 (architecture) → 구현 (implementation) → QA → 인간 검토 (human review). GitHub Issues와 연동되며, 실제 PR (Pull Request)을 생성합니다.

소프트웨어를 출시하는 것은 조정 (coordination)의 문제입니다. PM은 요구사항을 작성하고, 아키텍트는 타당성을 검증하며, 개발자는 코드를 작성하고, QA는 이를 테스트하며, 인간이 모든 것을 검토합니다. 각 단계는 지연, 의사소통 오류, 컨텍스트 유실을 초래하는 인수인계 과정입니다.

전통적인 프로젝트 관리 도구들은 이 프로세스의 *추적 (tracking)*을 자동화합니다. ACO는 이 프로세스의 *실행 (execution)*을 자동화합니다.

GitHub Issue
│
▼
...

모든 에이전트는 독립적으로 실행되며, 작업 여부를 확인 (poll)하고 결과를 공유 데이터베이스에 기록합니다. 메시지 전달 (message passing)이 없으며, 공유 컨텍스트 윈도우 (shared context window)도 없습니다. 스토리가 복잡해짐에 따라 성능이 저하되지도 않습니다.

특징	ACO System	LangChain Agents	AutoGen	CrewAI
구조화된 파이프라인 (Structured pipeline)	✅ 6-에이전트 게이트 체인 (gate chain)	❌	❌
결정론적 보안 게이트 (Deterministic security gate)	✅ 엄격한 프리 커밋 체크 (pre-commit checks)	❌	❌	❌
실시간 대시보드 (Real-time dashboard)	✅ 칸반 (Kanban) + 라이브 피드 + 알림	❌	❌	❌
인간 에스컬레이션 (Human escalation)	✅ 모든 단계에서 설정 가능
멀티 LLM 지원 (Multi-LLM support)	✅ 에이전트별 모델 오버라이드 (model override)
파일 기반 확장성 (File-based extensibility)	✅ 프롬프트 (Prompts), 규칙 (rules), 훅 (hooks), 기술 (skills)	❌	❌

아키텍트 (Architect) 에이전트가 핵심적인 차이점입니다. 코드가 작성되기 전에, LLM을 사용하지 않고 환각 (hallucination) 위험이 없는 **결정론적 검증 (deterministic validation)**을 수행합니다:

• ✅ 하드코딩된 비밀 정보 없음 (api_key, password, token, secret 스캔됨)
• ✅ 스토리에 tech_stack 및 acceptance_criteria 포함
• ✅ 모든 작업이 할당되고 추정됨

이 검증을 통과하지 못하면, 해당 스토리는 **게이트에서 거부 (rejected at the gate)**되며 개발자에게 전달되지 않습니다. 잘못된 PR, 유출된 자격 증명, 미완성된 기능이 발생하지 않습니다.

엔지니어링 팀 (Engineering teams) 중 반복적인 개발 워크플로우를 자동화하고자 하는 팀
AI/에이전트 연구자 (AI/agent researchers) 중 검증된 멀티 에이전트 협업 패턴을 기반으로 구축하려는 연구자
솔로 개발자 (Solo developers) 중 보일러플레이트 (Boilerplate) 작업을 처리할 "가상 팀"을 원하는 개발자
플랫폼 빌더 (Platform builders) 중 확장 가능한 에이전트 프리미티브 (Agent primitives)가 필요한 빌더

# 1. Clone
git clone https://github.com/aniketkarne/aco-system.git
cd aco-system
...

그게 전부입니다. 대시보드에는 칸반 보드 (Kanban board), 에이전트 상태, 스토리 타임라인 (Story timeline), 그리고 스트리밍 이벤트 피드 (Streaming event feed)를 포함한 라이브 파이프라인이 표시됩니다.

에이전트 (Agent)	모델 (Model)	역할 (Role)
PM	Sonnet	GitHub Issues로부터 사용자 스토리 (User stories)를 작성하고 웹 리서치를 수행함
Planner	Opus	스토리를 태스크 (Tasks)로 분할하고, 공수를 추정하며, 의존성 (Dependencies)을 매핑함
Architect	Opus	하드 게이트 (Hard gate): 타당성, 보안, 스키마 (Schema)를 검증하여 잘못된 스토리를 차단함
Developer	Sonnet	코드를 작성하고, 브랜치 (Branches) 및 PR을 생성하며, 코딩 표준을 준수함
QA	Sonnet	PR을 리뷰하고, 테스트를 작성 및 실행하며, 수락 기준 (Acceptance criteria)을 검증함
Human	—	예외 케이스에 대한 에스컬레이션 (Escalation) 지점 및 최종 머지 (Merge) 승인

모든 에이전트는 공유된 SQLite (개발용) 또는 PostgreSQL (운영용) 데이터베이스를 통해 통신합니다. 각 에이전트는 작업 여부를 폴링 (Polling)하고, 스토리 잠금 (Story lock)을 획득하며, 자신의 단계를 실행하고, 결과를 기록한 뒤 잠금을 해제합니다. 공유된 컨텍스트 윈도우 (Context window)는 없습니다. 에이전트 간의 API 호출도 없습니다. 복잡성은 에이전트 로직이 아닌 데이터베이스 스키마 (Database schema)에 머뭅니다.

ACO System은 GitHub를 대체하는 것이 아니라, 그 위에서 구축됩니다. 파이프라인의 모든 스토리는 자동으로 GitHub Issue를 생성하거나 연결하므로, 추가적인 도구 없이도 전체 히스토리, 라벨 (Labels), 검색 기능을 사용할 수 있습니다.

파이프라인 단계 (Pipeline Stage)	GitHub Action
PM이 스토리 생성	전체 설명, 수락 기준(Acceptance criteria), CEO/창업자 분석이 포함된 GitHub Issue 오픈
...

각 파이프라인 단계에는 상응하는 라벨이 있습니다. 대시보드의 칸반 보드는 이러한 라벨을 미러링(Mirroring)하므로, 보드와 GitHub Issues는 항상 동기화된 상태를 유지합니다:

pm-review → ready-planner → ready-architect → approved → dev → qa → human-review → done

Branches (브랜치)— feat/story-42-stripe-payments, fix/story-15-email-verification

Issues (이슈)— 스토리당 하나씩 생성되며, 본문에 전체 컨텍스트를 포함하고 스토리가 파이프라인을 통과함에 따라 업데이트됩니다.

Pull Requests (풀 리퀘스트)— 스토리당 하나씩 생성되며, 연결된 작업(tasks), 수락 기준(acceptance criteria)에서 가져온 설명, 그리고 테스트 지침을 포함합니다.

GitHub를 협업 레이어로 사용한다는 것은 다음을 의미합니다:

Lock-in (종속성) 없음— 데이터는 귀하의 것입니다. 대시보드를 닫더라도 에이전트들은 GitHub API만으로 계속 작동합니다.

기존 도구 활용— GitHub의 UI를 사용하여 검색, 필터링 및 분류(triage)를 수행할 수 있습니다. GitHub 설정을 통해 알림을 받으세요.

전체 감사 추적 (Full audit trail)— 모든 에이전트의 작업은 이슈 댓글에 기록됩니다. 모든 결정에는 타임스탬프가 찍히며 추적 가능합니다.

CI/CD 준비 완료— PR 생성 시 GitHub Actions가 트리거되어, QA 리뷰 전에 테스트 스위트(test suite)를 자동으로 실행합니다.

실시간 Next.js 대시보드는 전체 파이프라인에 대한 시각적 감독을 제공합니다. 이는 정적인 트래커가 아니라, 에이전트의 활동이 발생하는 대로 실시간으로 반영하는 도구입니다.

Kanban Board (칸반 보드) — 스토리는 각 파이프라인 단계를 나타내는 열(column)을 통해 이동합니다. 각 카드는 스토리 제목, 우선순위 배지 (critical / high / medium / low), 마지막 업데이트 이후 경과 시간, 그리고 거절 횟수를 보여줍니다. 열에는 PM Review, Planner, Architect, Dev, QA, Human Review, Done, 그리고 Blocked가 포함됩니다.

Agent Activity Panel (에이전트 활동 패널) — 6개의 에이전트 각각이 라이브 카드로 표시됩니다: 현재 상태 (idle / working / blocked), 처리 중인 스토리, 그리고 사용 중인 LLM 모델을 보여줍니다. 하단의 스트리밍 이벤트 로그는 에이전트의 작업을 실시간으로 타임스탬프와 함께 보여줍니다 — "aco-pm: New story created", "aco-architect: Approved story #12", "aco-dev: PR opened for task #4". 알림 패널은 거절, 에스컬레이션(escalations), 실패 사항을 즉시 표면화합니다.

Story Detail (스토리 상세 정보) — 카드를 클릭하면 설명, 수락 기준(acceptance criteria), 상태가 포함된 작업 목록, 대화 기록, 연결된 GitHub 이슈 등 전체 스토리 컨텍스트가 포함된 사이드 패널이 열립니다. 휴먼 리뷰어(human reviewer)는 최종 승인을 위해 이 뷰를 사용합니다.

모든 것은 파일 기반이며 핫 리로드(hot-reloadable)가 가능합니다. 에이전트의 동작에 영향을 주기 위해 코드를 변경할 필요가 없습니다:

확장 기능	형식	변경 사항
에이전트 프롬프트 (Agent prompts)	Markdown + YAML frontmatter	각 에이전트가 생각하고 결정하는 방식
코딩 규칙 (Coding rules)	rules/common/ 내의 Markdown	필수 표준 (보안, git 워크플로우, 테스트)
검증 훅 (Validation hooks)	hooks/ 내의 JSON	결정론적(Deterministic) 전/후 전환 확인
도메인 기술 (Domain skills)	skills/ 내의 Markdown	Python 패턴, FastAPI, React 등
프로젝트 컨텍스트 (Project context)	contexts/ 내의 Markdown	프로젝트별 배경 지식

aco-system/
├── agents/ # 에이전트 Python 구현체
│ └── base_agent.py # 새로운 에이전트를 추가하기 위해 상속
...

# 멀티 인스턴스 배포를 위한 PostgreSQL
DATABASE_URL=postgresql://user:password@host:5432/aco
# 분산 작업 큐를 위한 선택적 Redis
...

MIT License — LICENSE를 참조하세요.

Built by Aniket Karne