viettran-edgeAI/codex_workflow

codex_workflow – 토큰 효율적인 Codex 에이전트 오케스트레이션

개요

Python 기반 워크플로우 패키지로, Codex AI 어시스턴트(“Codex CLI/app”)를 구조화된 멀티 에이전트 실행 모드로 확장합니다. 사용자는 라이트, 미디엄, 헤비 경로를 선택할 수 있으며, 각 경로는 하위 에이전트(Explorer, Investigator, Executor, Tester, Archivist 등)의 수와 컨텍스트 공유 방식을 정의합니다.
워크플로우는 프로젝트 수준 메모리를 agent_docs/ 폴더에 저장하여 목표, 아키텍처 결정, 진행 노트 및 핸드오프 요약을 세션 간에 보존합니다.

중요성

대규모 언어 모델 에이전트는 토큰당 과금됩니다. 작업을 전문 하위 에이전트에 위임하고 결과를 배치 처리함으로써, codex_workflow는 메인 에이전트의 토큰 소비를 줄이면서 복잡한 다중 단계 작업을 가능하게 합니다.
사용자 정의 오케스트레이션 코드를 작성하지 않고도 많은 프로젝트에서 재사용할 수 있는 재현 가능한 “스웜” 패턴을 제공합니다.

빠른 시작 (설치)

다운로드 GitHub의 Releases 페이지에서 최신 릴리스 zip을 받습니다.
제공된 SHA256SUMS 파일로 다운로드를 검증합니다.
아카이브를 추출하고 포함된 codex_workflow/operate/bootstrap.md 지침을 따릅니다 (archivist 하위 에이전트를 통해 agent_docs/ 프레임워크를 생성합니다).
Codex 애플리케이션을 다시 시작합니다.

이제 모든 프로젝트 디렉토리에서 다음을 실행할 수 있습니다:

codex_workflow --install   # 해당 프로젝트에 워크플로우를 설정합니다.

요구 사항 – Python 3.11 이상 및 작동하는 Codex CLI/앱 설치.

워크플로우 사용 방법

경로	선택 시점	기능
라이트	간단한 Q&A, 빠른 수정	추가 하위 에이전트 없음. 메인 Codex 에이전트가 직접 응답합니다.
미디엄	연구나 문서화가 필요하지만 메인 에이전트가 여전히 구현/검증해야 하는 작업	Explorer(검색), Investigator(심층 분석), Archivist(메모 작성)를 실행합니다. 메인 에이전트가 코딩/검증을 수행합니다.
헤비	대규모 다학제 프로젝트 (예: 프론트엔드 디자인, 3D 시각화, 광범위한 테스트)	미디엄 스택에 Executor와 Tester를 추가합니다. 메인 에이전트는 오케스트레이션, 보고서 종합, 최종 결정만 수행합니다.

경로 전환 – Codex 채팅에서 다음을 입력합니다:

use medium route. <작업 설명>

또는 medium을 heavy로 바꿉니다. 선택한 경로는 변경할 때까지 활성 상태로 유지됩니다.

명령 실행 – 워크플로우에는 작은 CLI 래퍼가 포함되어 있습니다:

codex_workflow --install      # 현재 프로젝트 설정
codex_workflow --check-update # 최신 릴리스가 있는지 확인
codex_workflow --update       # 워크플로우 업그레이드
codex_workflow --remove       # 깨끗한 제거
codex_workflow --version      # 설치된 버전 표시

핵심 기능

영구 프로젝트 메모리 – agent_docs/가 목표, 아키텍처, 결정, 진행 상황 및 핸드오프를 자동으로 기록합니다.
토큰 인식 배치 처리 – 내장된 휴리스틱(v1.1.3 이후)이 메인 에이전트가 작업자를 생성하는 빈도를 제한하여 반복 컨텍스트 토큰을 줄입니다.
병렬 하위 에이전트 – 최대 3개의 작업자가 동시에 실행될 수 있습니다 (Codex 플랫폼은 세션당 총 4개의 에이전트로 제한).
증거 링크 보고서 – 작업자는 전체 로그/아티팩트를 참조하는 간결한 요약을 반환하여 메인 에이전트의 컨텍스트를 작게 유지합니다.
시니어 실행기 폴백 – 특히 어려운 문제의 경우 더 높은 용량의 실행기가 자동으로 호출될 수 있습니다.
세션 종료 토큰 통계 – 각 실행 후 각 에이전트가 사용한 토큰 수의 분석을 받습니다.
사용자 정의 가능한 정책 파일 – 전역 설정은 ~/.codex/AGENTS.md에 저장되고, 프로젝트별 재정의는 agent_docs/와 함께 저장됩니다.

벤치마크 및 성능

저장소에는 배치 처리 지침이 가장 큰 비용 요인인 메인 에이전트의 캐시된 입력 토큰을 줄이는 방법을 보여주는 라이트 벤치마크가 포함되어 있습니다. 시각 분석(light_benchmark/analysis.png)과 벤치마크 확장 제안이 제공됩니다.

제한 사항 및 고려 사항

워크플로우는 Codex 플랫폼의 현재 4개 동시 에이전트 제한에 의존합니다. 플랫폼 변경 없이는 더 큰 스웜은 불가능합니다.
헤비 경로 작업은 메인 에이전트의 롤아웃이 줄어들지만 더 많은 하위 에이전트가 활성화되어 전체적으로 더 많은 토큰을 소비합니다.
설치 프로세스는 zip 자산을 수동으로 다운로드하고 검증해야 합니다. 아직 pip 스타일 설치 프로그램이 없습니다.
토큰 절약 휴리스틱은 작성자의 실험에 맞게 조정되었습니다. 결과는 다른 LLM 제공업체나 모델 버전에 따라 다를 수 있습니다.

자세히 알아보기

전체 아키텍처, 수명 주기 및 안전 노트: workflow_breakdown.md
벤치마크 아이디어 및 새 테스트 기여 방법: benchmarks/README.md
에이전트 수명 주기 세부 사항: codex_workflow/agent_lifecycle.md

결론 – codex_workflow는 Codex 파워 유저가 빠른 답변부터 대규모 개발 프로젝트까지 다중 에이전트, 토큰 효율적인 파이프라인을 실행하면서 프로젝트 전체 지식 기반을 자동으로 유지할 수 있는 즉시 사용 가능한 오케스트레이션 계층입니다.