AgentWeaver

AgentWeaver는 코딩 에이전트 주변에 내구성 있는 워크플로우를 설계하기 위한 TypeScript/Node.js CLI입니다.

이는 에이전트 작업이 일회성 프롬프팅(one-off prompting)처럼 행동하는 것이 아니라, 검사 가능한 엔지니어링 시스템처럼 작동하기를 원하는 팀을 위해 구축되었습니다: 명시적인 워크플로우, 내구성 있는 아티팩트(durable artifacts), 반복 가능한 리뷰 게이트(repeatable review gates), 재개 가능한 실행(resumable execution), 그리고 코드베이스와 함께 진화하는 레포지토리 로컬 가이던스(repository-local guidance)를 제공합니다.

일반적인 사용 사례는 다음과 같습니다:

plan -> implement -> run-go-linter-loop -> run-go-tests-loop -> review -> review-fix

계획 수립에 중점을 둔 작업은 다음을 사용할 수 있습니다:

plan -> design-review -> implement -> review-loop

중요한 부분은 정확한 체인(chain) 자체가 아닙니다. 핵심은 AgentWeaver가 에이전트를 둘러싼 하네스(harness)를 모델링하고, 운영하며, 진화시킬 수 있게 한다는 것입니다.

확장된 기능 개요는 docs/features.md를 참조하십시오.

선언적 에이전트 워크플로우 (Declarative agent workflows): 플로우는 단계(phases), 스텝(steps), 프롬프트 바인딩(prompt bindings), 파라미터(params), 기대치(expectations), 그리고 후속 스텝 액션(post-step actions)을 가진 JSON 사양입니다. 워크플로우 설계가 선언적으로 유지되는 동안 런타임 동작은 타입이 지정된 노드와 실행기(executors)에 존재합니다.레포지토리 로컬 프로젝트 플레이북 (Repository-local project playbook): 안정적인 프로젝트 컨벤션은 .agentweaver/playbook/ 아래 버전 관리 규칙, 예제 및 템플릿으로 존재합니다. 가이드된 플로우는 계획 수립, 구현, 리뷰 및 수정 전에 관련 가이던스를 선택하여 반복되는 에이전트 실행이 동일한 프로젝트 지식을 상속받도록 합니다.아티팩트 우선 실행 (Artifact-first execution): 각 단계는 디스크에 구조화된 JSON과 사람이 읽을 수 있는 마크다운 아티팩트를 생성합니다. 아티팩트는 스테이지 간의 계약(contract)이며, 이를 통해 실행은 검사 가능하고, 리뷰 가능하며, 재시작 가능해집니다.계획 및 디자인-리뷰 게이트 (Planning and design-review gates): 계획 워크플로우는 디자인, 구현 계획 및 QA 계획 아티팩트를 생성합니다. design-review는 코딩을 시작하기 전에 이러한 아티팩트를 비평하고, 내장된 auto...

워크플로우는 구현 전에 디자인 검토 게이트를 포함합니다.검토 및 수정 루프: 검토 플로우는 심각도(severity)가 지정된 구조화된 발견 사항을 생성합니다. 수정 플로우는 블로커(blockers) 및 중요 발견 사항을 선택하고, 목표 지정을 적용하며, 후속 확인을 실행할 수 있습니다.재개 가능한 자동화: 장시간 실행되는 플로우는 압축된 실행 상태를 유지하여 재개/계속/다시 시작 의미론을 지원하며, 아티팩트(artifacts)와 런칭 프로파일이 호환될 경우 선택된 단계부터 다시 시작할 수 있습니다.다중 실행 백엔드: Codex, OpenCode, 셸/프로세스 검사, Jira, GitLab, Git 커밋 및 Telegram 알림 통합을 공통 실행기 모델을 통해 실행합니다.대화형 TUI, 웹 UI 및 직접 CLI: 동일한 워크플로우 모델이 운영자 주도 인터페이스, 직접 CLI 명령어, 비대화형 자동화에서 작동합니다.사용자 정의 플로우: 내장된 플로우는 AgentWeaver 소스 코드를 변경하지 않고 전역 또는 프로젝트 로컬 플로우 스펙으로 확장할 수 있습니다.플러그인 SDK: 로컬 플러그인은 매니페스트 유효성 검사, 버전 확인 및 문서화된 진입점 규칙을 통해 공개 SDK 호환 노드와 실행기를 추가할 수 있습니다.운영 진단(doctor):doctor 체크는 워크플로우가 실행 도중에 실패하기 전에 시스템 준비 상태, 실행기 구성, 플로우 스펙, 노드 버전 및 런타임 환경 구성을 확인합니다.

AgentWeaver는 단일 에이전트 호출을 둘러싼 얇은 래퍼(wrapper)로 포지셔닝되지 않았습니다. 이는 하네스 엔지니어링(harness engineering)을 위한 것입니다:

• 워크플로우가 긴 프롬프트 안에 숨겨져 있는 것이 아니라 명시적입니다.
• 중간 결정 사항이 채팅 기록에 사라지는 대신 영구 저장됩니다.
• 에이전트는 메모리나 복사/붙여넣기된 지침에 의존하는 대신 리포지토리로부터 프로젝트 가이던스를 받습니다.
• 검토, 수정, 검사 및 재시작 동작은 워크플로우의 일급(first-class) 구성 요소입니다.
• 동일한 모델이 로컬 CLI 사용, 대화형 운영, 자동화에서 작동합니다.

실제적으로 이는 에이전트 워크플로우를 버전 관리되고, 검사 가능하며, 반복 가능하고, 디버깅 가능한 엔지니어링된 시스템처럼 다룰 수 있음을 의미합니다.

flow spec

: src/pipeline/flow-specs/에 있는 선언적 JSON입니다.

, global~/.agentweaver/.flows/``,

, 또는 project-local.agentweaver/.flows/``

`node``:
src/pipeline/nodes/에서 재사용 가능한 런타임 유닛

`executor``:
Jira, Codex, OpenCode, GitLab, shell/process 실행, Telegram 알림 및 관련 액션에 대한 통합 계층

`scope``:
아티팩트와 플로우 상태를 위한 격리된 작업 공간 키입니다. 일반적으로 Jira 태스크를 기반으로 하며, 그렇지 않으면 git 컨텍스트에서 파생됩니다.

`artifact``:
플로우에 의해 생성되거나 소비되는 파일로, 스테이지 간의 안정적인 계약 역할을 합니다.

flow state``: 장시간 실행되는 플로우(예: auto`)에서 재개/재시작을 위해 사용되는 압축된 영속적 실행 메타데이터입니다.

auto`` project playbook``:
local.agentweaver/playbook/ 디렉터리로, manifest.yaml, 모범 사례, 예제 및 템플릿이 포함되어 있습니다. 형식은 docs/playbook.md에 설명되어 있습니다.

`resume``
진정으로 중단된 실행만 재개하며, 이미 완료된 단계를 다시 구축하지 않고 저장된 실행 상태를 사용합니다.

`continue``
완료된 반복 주기용이며, 기존 아티팩트를 삭제하지 않고 최신 유효 아티팩트부터 다음 반복을 시작합니다.

restart`` 새로운 실행으로 처리됩니다. 엔드투엔드 시도 플로우의 경우, 현재 활성 시도는 새로운 시도가 시작되기 전에 .agentweaver/scopes/<scope>/.artifacts/restart-archives/attempt-XXXX아래에 아카이브됩니다. 독립적인 단일 목적 플로우의 경우, 재시작은 해당 플로우의 저장된 상태만 초기화하고 기존 스코프 아티팩트는 사용 가능하게 유지합니다.- 모호한 실행의 경우, 운영자는 명시적으로 조치를 선택해야 합니다: 대화형 모드에서는 확인을 통해, 비대화형 모드에서는--resume, --continue또는--restart`를 사용하여

• 이 계약은 auto, auto-config:<name>, instant-task, review-loop, run-go-linter-loop, 및 run-go-tests-loop에 적용됩니다.
  시스템의 중심은 선언적 플로우 사양입니다:

• phases는 운영자에게 보이는 워크플로우 구조를 정의합니다.

• steps는 각 단계(phase) 내부의 실행 단위를 정의합니다.

• prompt bindings는 에이전트 지침이 어떻게 조립되는지를 정의합니다.

• params는 노드 런타임 입력을 정의합니다.

• expectations는 사후 조건(postconditions)을 정의합니다.
  after

actions는 임시적인 명령형 연결고리(ad-hoc imperative glue)를 도입하지 않고 런타임 상태를 업데이트합니다.

이를 통해 워크플로우 설계는 JSON으로 유지하면서 구현 세부 사항은 타입이 지정된 런타임 코드에 유지할 수 있습니다.

전체 flow-spec 참조는 이제 docs/declarative-workflows.md에 위치합니다.

src/index.ts

— CLI 진입점, 인터랙티브 모드 부트스트랩 및 최상위 오케스트레이션
src/executors/

— 일급 실행기(first-class executors)
src/executors/configs/

— 데이터 전용 기본 실행기 설정
src/pipeline/

— 선언적 플로우 로딩, 컴파일, 검증, 런타임 및 내장 플로우 스펙
src/pipeline/nodes/

— 플로우 스펙에서 사용되는 재사용 가능한 런타임 노드
src/runtime/

— 명령어 해결(command resolution) 및 서브프로세스 실행과 같은 공유 런타임 서비스
src/interactive/

— Ink 기반 인터랙티브 세션, 컨트롤러, 상태 및 뷰 모델 로직
src/markdown.ts

— 터미널 출력을 위한 마크다운 렌더링
src/structured-artifact-schemas.json

— 기계가 읽을 수 있는 아티팩트를 위한 스키마
tests/

— 파이프라인 동작에 대한 자동화된 테스트

사용자가 호출할 수 있는 내장 명령어는 현재 다음 플로우 스펙과 매핑됩니다:

plan

— Jira의 정규화된 작업 소스 또는 수동 입력을 사용하고, 개발자에게 명확히 하는 질문을 생성하며, 답변을 수집하고, 구조화된 JSON 및 마크다운 아티팩트로 설계, 구현 계획 및 QA 계획을 생성합니다.
design-review

— 최신 계획 아티팩트에 대한 구조화된 비평을 수행하고 전용 design-review/v1 아티팩트를 작성합니다.
approved_with_warnings

진행 준비가 된 것으로 간주되며 여전히 ready-to-merge.md를 생성할 수 있습니다.
task-describe

— Jira 이슈 또는 수동 입력으로부터 간략한 작업 설명을 생성합니다. Jira가 제공되면 해당 이슈를 가져와 요약하고, 그렇지 않으면 자유 형식 텍스트를 받아 코드베이스를 분석하여 더 풍부한 설명을 생성합니다 (implement)

— 이전에 승인된 설계 및 계획 아티팩트를 기반으로 LLM 지원 구현을 실행합니다. 프로젝트 작업 디렉터리에서 코드를 로컬로 실행하는 기능입니다 (review)

— 현재 변경 사항에 대해 작업 설계 및 계획과 비교하여 코드 리뷰를 수행합니다. 심각도 수준과 병합 준비 완료 여부를 갖춘 구조화된 검토 결과를 생성합니다 (review-fix)

— 검토 결과를 받아 블로커(blockers)와 중요 문제점(criticals)을 자동 선택하거나 (개발자가 수동으로 선택하게 하거나), 목표 수정 프롬프트를 구성하고 로컬에 수정을 적용합니다. 수정 후 필수 확인 절차를 실행합니다 (review-loop)

— 리뷰 → review-fix 사이클을 최대 5회 반복적으로 실행합니다. 병합 준비 완료 상태가 되면 조기에 중단됩니다. 각 반복마다 블로커 및 중요 문제점 발견 사항을 자동으로 선택하여 수정합니다 (bug-analyze)

— Bug 유형의 Jira 이슈를 가져오거나 Jira 사용이 불가능할 때 수동 작업 텍스트를 받아, (Jira 기반 실행의 경우) Jira 이슈 유형만 검증하고, 캐시된 작업 요약을 생성하거나 재사용하며, 구조화된 버그 분석(근본 원인 가설, 수정 설계, 단계별 수정 계획)을 생성합니다 (bug-fix)

— bug-analyze에서 설계한 수정을 적용합니다. 근본 원인 가설, 수정 설계 및 수정 계획 아티팩트를 진실의 출처로 사용하여 로컬에 코드 변경 사항을 구현합니다 (git-commit)

— 4단계 커밋 워크플로우: git 상태와 diff를 수집하고, LLM을 통해 커밋 메시지를 생성하며, 파일 선택 양식을 제시한 다음, 확인용 편집 가능한 메시지를 보여주고 커밋을 실행합니다 (gitlab-diff-review)

— GitLab 병합 요청(merge request) URL을 프롬프트로 받아, GitLab API를 통해 MR diff를 가져오고, LLM 지원 코드 리뷰를 실행하여 심각도 수준과 병합 준비 완료 여부를 갖춘 구조화된 발견 사항을 생성합니다 (gitlab-review)

— GitLab 병합 요청(merge request) URL에 대한 프롬프트; GitLab API를 통해 기존 코드 리뷰 코멘트를 가져오고, 어떤 발견 사항이 타당하고 어떤 것을 무시할 수 있는지 평가한 다음, 승인된 발견 사항에 대해 수정 사항을 적용하기 위해 review-fix를 실행합니다.

— 작업 컨텍스트와 현재 코드 변경 사항을 기반으로 간결한 병합 요청 설명을 생성하며; 마크다운과 구조화된 JSON 아티팩트 모두를 생성합니다 (run-go-tests-loop).

— run_go_tests.py를 실행하고 실패를 분석합니다. 테스트가 실패하면, 오류 출력을 LLM에 보내 수정하도록 요청하고 재시도합니다. 성공할 때까지 최대 5회 반복하며, 조기에 중단됩니다 (run-go-linter-loop).

— run_go_linter.py를 실행하고 출력을 분석합니다. linter가 문제를 보고하면, 이를 LLM에 보내 수정하도록 요청하고 재시도합니다. 성공할 때까지 최대 5회 반복하며, 조기에 중단됩니다 (auto).

— 단일 내장 Auto 워크플로우: 작업 소스 → 정규화(normalize) → 계획(plan) → 설계 검토 루프(design-review loop) → 구현(implement) → 검토 루프(review loop). 이는 불변적이며, 사용자 정의 변형은 auto-config:<이름>으로 저장됩니다.

.doctor

— 시스템, 실행기(executor), 흐름 준비 상태에 대한 건강 검사(health checks)를 실행하는 진단 명령입니다. 카테고리 또는 체크 ID별로 필터링하고 JSON 출력을 지원합니다.

또한 review-project와 같이 선언적으로 로드되지만 직접적인 최상위 CLI 명령어는 아닌 내장 중첩/헬퍼 흐름도 있습니다 (이전에 설계/계획 아티팩트가 없을 때 내부적으로 사용되는 프로젝트 수준 코드 리뷰).

TUI(Text User Interface) 및 Web UI는 실행 가능한 흐름을 표시 카탈로그로 구성합니다. 이는 탐색만 변경하며, CLI 명령어 ID, 흐름 ID, 재개 상태(resume state), 라우팅 키는 안정적입니다.

Recommended는 기본적으로 첫 번째이며 확장되며, Auto와 Instant task를 포함합니다.

.Auto는 사용 가능한 경우 기본적으로 선택됩니다. Custom은 저장된 Auto 구성, 프로젝트 로컬 흐름, 그리고 전역 흐름을 각각 Saved auto flows, Project flows, Global flows 아래에 포함합니다.

.Built-in blocks는 숙련된 사용자를 위한 접힌 라이브러리입니다. 여기서는 재사용 가능한 실행 가능 항목들을 Core pipeline, Quality checks, Task utilities, Delivery, Integrations 아래에 그룹화합니다.

그리고 'Specialized'(특화된)

카탈로그 용어는 런타임 구현과 의도적으로 분리되어 있습니다:

• 레시피(recipe)는 auto, instant-task, 또는 auto-config:<이름>과 같은 최종 사용자 시나리오입니다. - 블록(block)은 plan, design-review, implement, review, review-fix, review-loop, run-go-tests-loop, 또는 run-go-linter-loop와 같은 재사용 가능한 파이프라인 단계입니다. - 도구(tool)는 task-describe, playbook-init, git-commit, 또는 mr-description과 같은 인접한 작업을 지원합니다. - 통합(integration)은 주로 gitlab-review나 gitlab-diff-review와 같은 외부 시스템과 연동하여 작동합니다. - 특화된 흐름(Specialized flows)은 bug-analyze 및 bug-fix와 같이 더 좁은 작업 클래스를 다룹니다.

• Node.js
  >= 18.19.0

• npm
  codex

Codex 기반 단계용 CLI: opencode
OpenCode 기반 단계를 사용하는 경우의 CLI - 선택된 흐름이 Jira 및/또는 GitLab에 접근해야 할 때 사용합니다.

The agentweaver web [--no-open] [--host <호스트>|--listen-all] [<jira-browse-url|jira-issue-key>] 명령은 Web UI를 통해 대화형 모드를 시작합니다. 기본적으로 서버는 127.0.0.1에 바인딩하고, 운영 체제에 무작위 포트를 요청한 다음, 최종 주소를 AgentWeaver Web UI: http://127.0.0.1:<포트>/로 출력합니다.

신뢰할 수 있는 네트워크의 다른 컴퓨터에서 Web UI를 열려면 먼저 Web UI 자격 증명을 구성해야 합니다: