claude-workflow-mods

Claude Code의 작업을 의존성 그래프(DAG)로 나누어 실행하는 Claude Mod 플러그인입니다.
독립된 작업은 병렬로 실행하고, 선행 작업이 끝나면 그 결과를 다음 작업에 전달합니다.

• 병렬 실행: Claude Code 서브에이전트가 의존 관계에 따라 작업합니다.
• 결과 검증: 노드마다 정해 둔 검사를 통과해야 완료로 처리하며, 기대 불충족과 실행 불가·판정 불가를 구별해 기록하고 각 상태의 의미와 대응 방법을 에이전트에 전달합니다.
• 진행 상황 표시: DAG 패널에서 작업 상태와 의존 관계를 확인합니다.
• 보드: 모델이 흐름도·호출 순서·표·핵심 코드를 한 장의 보드에 그려 패널의 보드 섹션에 보여 줍니다.
• 세션 학습: DAG 밖의 대화와 작업까지 학습해 재사용할 스킬을 만들고, 이후 세션에 관련 지식을 제공합니다.
• 검토 기준: 테스트·검사 정책을 약화해 얻은 통과를 검토하고, 선택한 실행에는 에이전트 신뢰 경계 가이드(review.security: [agent])를 적용합니다. 검증과 검토에 자세한 기준이 있습니다.
• 시큐어코딩 스캔: semgrep이 설치되어 있으면 KISA 보안약점 규칙(Python·JavaScript/TypeScript·Java, 23개 항목)을 편집마다 실행합니다. 하드코드된 비밀값은 파일에 쓰기 전에 막고, review.security 실행에서는 규칙 히트마다 반박 검증 노드를 붙입니다. Semgrep 규칙 스캔에 범위와 한계가 있습니다.
• 실행 기록(trajectory): trajectory_log를 켜면 노드 시도마다 받은 프롬프트 원문, 모델, 답, 검증 결과, 검토 노트, 변경 diff, 토큰 사용량, 도구 호출 기록과 메인 대화의 턴을 .claude/dag/trajectories/에 남깁니다. 같은 정의를 여러 번 실행해 결과가 갈린 지점을 비교할 때 씁니다. 실행 기록에 형식이 있습니다.
• 실행 진단: 기존 수정 스캐너는 테스트 약화를 경고하고, 같은 실패의 반복 실행은 도구 결과에 안내합니다. 복구 판단에는 검증 로그에서 확인한 의존성·연결·권한 오류 근거를 제공합니다.
• 판단 호출 제한: 동일한 진행 중 Jev 요청은 합치고, jev_max_calls(기본 100)로 로드된 세션의 판단 호출 수를 제한합니다. 상한에 도달하면 자동 승인 없이 기존 판단으로 돌아갑니다.

실행 화면

선행 작업인 settings가 끝난 뒤 greeter와 repeater가 병렬로 실행되는 화면입니다. 오른쪽 패널은 작업별 상태와 의존 관계를, 프롬프트 위 밴드는 현재 진행 상황을 보여 줍니다.

빠른 시작

Claude Code **v2.1.299 이상(Claude Mods 기능 포함)**이 필요합니다. 이 저장소를 내려받은 뒤, 작업할 프로젝트 디렉터리에서 플러그인을 불러옵니다.

claude --plugin-dir /path/to/this-repo

/path/to/this-repo는 이 저장소의 실제 경로로 바꿉니다.
모든 세션에 적용하려면 전역 불러오기 설정을 참고하세요.

이후에는 평소처럼 요청합니다.
DAG를 직접 작성하거나 별도로 실행을 지시할 필요는 없습니다.

설정 파일을 공유하는 인사 함수와 텍스트 반복 함수를 만들고,
두 함수를 사용하는 CLI와 테스트까지 작성해줘.

기본 auto 모드에서는 요청에 따라 직접 실행하거나 DAG로 나눕니다. DAG로 실행하면 진행 알림이 나오고, 실행이 끝나면 노드별 결과와 검증 요약이 대화에 전달됩니다.

기본 사용법

진행 확인

/dag                        DAG 패널 열기
/dag list                   이 프로젝트의 실행 목록
/dag status <run_id>        실행의 노드별 상태

패널에서는 그래프·레인·타임라인 보기를 선택할 수 있습니다. 패널을 닫아도 프롬프트 주변에 진행 상황이 표시됩니다. Esc로 프롬프트로 돌아갑니다.

패널은 터미널, 데스크톱, VS Code 채팅 패널에서 표시되며, 모바일 같은 다른 화면에서는 진행·완료 메시지를 텍스트로 받습니다.

이 세션의 실행이 완료 또는 실패로 끝나면 Claude Code 알림(preferredNotifChannel 설정과 Notification 훅이 따르는 그 알림)으로 실행 이름·결과·노드 수를 한 번 알립니다. settle_notify 기본값 long에서는 만든 지 120초 이상 걸린 실행만 알리고, off는 끄며, always는 모든 실행을 알립니다. 취소된 실행과 다른 세션의 실행은 알리지 않습니다.

취소와 재시도

/dag cancel <run_id>           실행 취소
/dag retry <run_id> [node...]  실패·취소된 노드 다시 실행
/dag answer <run_id> <node> <text>  막힌 노드의 질문에 답하기

노드가 실패하면 그 결과가 필요한 후속 작업은 시작하지 않고, 관계없는 작업은 계속 실행합니다. 재시도할 때 이미 완료된 노드의 결과는 재사용합니다. 노드가 질문하며 멈추면(blocked) 패널 버튼이나 /dag answer로 답합니다. 자세한 내용은 레퍼런스의 노드 질문을 보세요. 실패한 노드는 ## Output 끝에 Next:(다음에 볼 가설)와 Tried and failed:(시도했다가 실패한 방법)를 남기고, 자동 재시도는 이 두 줄을 받아 같은 시도를 되풀이하지 말라는 지시와 함께 전달합니다. 직접 실행하는 /dag retry에는 전달되지 않습니다. 노드가 작업 중 스스로 정한 사항은 Ruling: 줄로 남고, 실행이 끝나면 메인 대화가 받는 요약에 노드별로 모아 보여 줍니다.

정의 파일 실행

직접 작성한 DAG는 JSON 또는 YAML 파일로 실행할 수 있습니다.

/dag preview <file>          실행 전 계획·쓰기 충돌·경고 확인
/dag run <file>              정의 파일 실행

프롬프트에서 /dag run 이나 /dag preview 뒤에는 flows/와 eval/fixtures/의 정의 파일 경로가, /dag status·cancel·retry·approve·reject·handoff·accept 뒤에는 이 프로젝트의 실행 id가 자동 완성 후보로 나옵니다.

작성 예제와 필드는 정의 형식을 참고하세요.

보드로 구조 보기

구조나 흐름을 말보다 그림으로 보여 주는 편이 나을 때, 모델이 mcp__dag-workflow__board 도구로 보드를 그립니다. 보드는 /dag 패널의 보드 섹션에 나타나며, 패널에서 b를 누르거나 /dag inspect board로 엽니다.

/dag inspect board          패널을 보드 화면으로 열기

보드는 다음 경우에 쓰입니다.

• 표시 방식 판단: auto에서 Jev가 실행 방식과 함께 답을 채팅과 보드 중 어디에 보여 줄지(표시 방식)도 판단합니다. 여러 부분이 얽힌 것을 이해하려는 요청이고 파일 변경을 요구하지 않으면 보드로 답합니다. 조건과 동작은 표시 방식 판단에서 확인하세요.
• 인터뷰·PM 스킬: /dag-workflow:interview와 /dag-workflow:pm은 질문하는 동안 모호함 표와 설계 트리, 제품 결정·미룬 결정·미해결 항목 표를 보드에 그리고 라운드마다 갱신하며, 보드를 보여 줄 수 없으면 대화에 출력합니다.
• 직접 요청: 사용자가 보드로 보여 달라고 하면 모델이 도구를 직접 호출합니다.

DAG의 실행 수명 주기는 보드 도구를 스스로 부르지 않습니다. 플러그인은 실행이 끝나도 보드를 그리지 않으며, 실행의 진행과 기록은 DAG 패널과 그 inspector가 보여 줍니다. 표시 방식이 보드로 판단된 요청을 DAG로 실행하면 정산 메시지가 모델에게 검증한 발견을 보드에 그리고 열라고 안내할 뿐입니다. start_approval로 보류된 실행의 승인 블록은 이 세션에 보드가 있으면 가장 나중에 고친 보드를 가리킵니다.

DAG와 보드는 역할이 다릅니다.

DAG	보드
하는 일: 변경을 만듭니다. 서브에이전트 노드를 의존 관계에 따라 병렬로 실행하고, 노드마다 격리된 컨텍스트에서 일하며, 결과를 검증하고 실패를 복구합니다.	하는 일: 사용자가 이해하려는 답을 보여 줍니다. 다이어그램, 표, 인용한 코드가 /dag 패널에 남고 블록 칩으로 프롬프트에 다시 인용할 수 있습니다.
강점: 노드가 셋 이상인 큰 변경을 나눠 병렬로 처리하고, 정해 둔 검사를 통과한 결과만 완료로 인정하며, 실패한 노드는 재시도하거나 복구합니다.	강점: 여러 부분이 얽힌 구조·흐름·비교를 말보다 한눈에 보여 주고, 그릴 때 읽은 코드 줄을 그대로 남기며, 프로젝트 파일은 바꾸지 않습니다.
알맞은 요청: 파일을 바꾸고, 병렬·격리 실행이 유리한 요청	알맞은 요청: 시스템이 구성요소에 걸쳐 어떻게 동작하는지, 선택지 비교, 변경이 파일 여럿에서 한 일, 트레이드오프가 있는 결정, 조사 결과

보드는 section, callout, table, code_peek, code, trace, diff, flow, sequence, board_ref, divider 열한 가지 블록으로 이루어집니다. code_peek은 파일의 몇 줄을 그릴 때의 내용 그대로 보여 주고(ref를 주면 워킹 트리 대신 그 git ref 시점의 줄), code는 모델이 제안하는 코드 조각을, trace는 이 세션 실행의 노드 산출물(출력·답변·오류·검증 보고서)을 그릴 때의 내용 그대로 인용합니다. diff는 호스트가 git diff <ref>(path가 있으면 그 파일만)로 읽은 변경을 인용합니다. flow에는 순환하는 간선을 그릴 수 없고, 간선에 style: 'dashed'를 주면 점선 관계로 표시되며 sequence의 단계에는 note를 달 수 있습니다. board_ref는 같은 세션의 다른 보드를 가리키는 링크(패널에서 누르면 그 보드로 갑니다)이고 divider는 가로 구분선입니다. edit의 move 연산은 블록을 afterId 뒤로 옮깁니다. 보드는 세션마다 .claude/dag/boards/에 저장하며, 다른 산출물처럼 보관 기간(retention_days)이 지나면 정리합니다. /dag accept로 실행을 인계받은 세션은 원래 세션의 보드도 함께 가져옵니다. 보드 섹션에서 블록 머리글을 누르면 그 블록이 칩으로 프롬프트에 들어가고, 칩을 담아 보낸 프롬프트에는 그 블록의 내용이 함께 전달됩니다. 도구의 export 액션은 보드를 마크다운 문서로 직렬화합니다. 도구 입력과 블록별 제한은 보드에서 확인하세요.

세션 전체에서 학습하기

플러그인이 로드된 세션에서는 일반 대화, 메인 작업과 서브에이전트의 결과도 학습 대상입니다. 사용자 요청에 대한 메인 답변이 끝나면 Sonnet 학습 에이전트가 백그라운드에서 재사용할 교훈을 추출합니다. 새로 학습한 스킬은 항상 이 프로젝트의 .claude/dag/skills/에 저장하고 같은 프로젝트에서만 안내합니다. 여러 프로젝트에 쓸 만한 기법이어도 ~/.claude/skills에는 새로 쓰지 않습니다. 이전에 학습한 스킬은 ~/.claude/skills에 그대로 두고 플러그인이 계속 관리하며, 지울지는 사용자가 정합니다. 학습 에이전트의 사용량은 Claude 요금제에 포함됩니다.

/dag learn                  아직 학습하지 않은 세션 경험을 지금 학습
/dag learning               학습 상태, 이 프로젝트에서 쓰는 스킬과 변경 근거 확인
/dag learning off           현재 세션의 학습 끄기
/dag learning on            현재 세션의 학습 켜기

기본값은 session_learning: true이며, 자동 학습은 모든 세션을 합쳐 UTC 하루 20회까지 실행합니다. 전체 학습 입력은 60,000자 이내이고, 오래된 비활성 세션 자료와 보관 스킬은 기본 30일 뒤 정리합니다. 세션 학습에서 제한 설정과 저장·복구 정책을 확인하세요.

실행 방식과 주요 설정

설정은 /config의 플러그인 항목에서 바꿉니다. 실행 방식은 /dag enforce <모드>로 현재 세션에서도 변경할 수 있습니다.

실행 방식

• auto (기본): Jev가 요청마다 판단합니다. 작은 요청은 직접 실행하고, 노드가 셋 이상 필요하며 병렬·격리 실행이 유리한 요청은 DAG로 실행합니다. 같은 판단이 답을 채팅과 보드 중 어디에 보여 줄지(표시 방식)도 정합니다.
• strict: 실제 작업은 모두 DAG 노드에서 실행합니다. 메인 대화는 계획·읽기·질문·실행 관리만 담당합니다.
• guide: DAG 사용을 안내하지만 메인 대화의 도구 사용을 제한하지 않습니다.
• off: DAG 강제와 관련 안내를 끕니다.

auto에서 판단이 불확실하거나 실패하면 직접 실행합니다. 단, 현재 세션에 아직 끝나지 않은 실행이 있으면 DAG 방식으로 유지합니다.

자주 바꾸는 설정

• language: 패널 언어. 기본 en, 한국어는 ko.
• max_concurrent: 실행 하나에서 동시에 작업할 노드 수. 기본 8.
• start_approval: 기본 off. always로 설정하면 대화형 세션에서 모델이 시작한 실행은 사용자 승인을 기다립니다.
• settle_notify: 기본 long. 실행이 완료·실패로 끝났을 때 Claude Code 알림을 보내는 조건입니다. long은 만든 지 120초 이상 걸린 실행만, always는 모든 실행, off는 알리지 않습니다.
• usage_hold_percent: 기본 90. 계정 한도 창(5시간, 7일, 게이트웨이의 지출 한도) 중 하나라도 이 퍼센트 이상 찼으면 이 세션의 실행이 새 노드를 시작하지 않고 기다립니다. 이미 실행 중인 노드는 계속 돕니다. 0은 끄고, 0–100이 아닌 값은 90으로 처리합니다.
• auto_recovery: 기본 true. 조건에 맞는 실패를 자동으로 복구합니다.
• review_ledger: 기본 true. 리뷰 수정 라운드가 지적과 수정 diff를 다시 도는 리뷰어에게 전달합니다. false면 이전 프롬프트를 씁니다.
• notify: 기본 true. 노드가 권한 답변이나 질문 답을 기다릴 때, 자동 복구가 재시도를 멈췄을 때 네이티브 알림을 보냅니다. 실행이 끝났을 때의 알림은 settle_notify가 따로 정합니다. 알림이 가지 않아도 토스트는 뜹니다.

시작 승인을 켰다면 패널 버튼이나 /dag approve <run_id>로 승인하고, /dag reject <run_id> [reason]으로 거절합니다. 직접 입력한 /dag run과 비대화형 세션은 시작 승인을 기다리지 않습니다.

자동 판단과 사용량

Typesafe 의 Jev(System One Model)는 실행 방식, 노드의 모델 등급, 도구 승인, 실패 복구를 판단합니다.
TYPESAFE_API_KEY가 있으면 TypeSafe API를 사용하고, 키가 없거나 API가 실패하면 기본적으로 세션의 Sonnet 모델을 사용합니다. 세션 모델의 판단 호출은 사용자의 Claude 요금제 사용량에 포함됩니다.

계정 한도가 가까워지면 새 노드를 시작하지 않고 기다립니다. Claude Code가 알려 주는 한도 창(5시간, 7일, 게이트웨이의 지출 한도) 중 하나라도 usage_hold_percent(기본 90%) 이상 찼으면 이 세션의 실행은 새 노드를 시작하지 않고, 이미 실행 중인 노드는 계속 돕니다. 처음 멈출 때 토스트가 한 번 뜨고, 이 세션의 실행을 보여 주는 패널 헤더에 한도 대기: ...가 표시됩니다. 수치는 Claude Code 상태 줄의 값이라 세션 시작 때 읽고, 메인 턴이 끝날 때마다 그리고 창이 1%p 움직일 때마다 갱신합니다. 수치가 없는 API 키·게이트웨이 세션은 대기하지 않으며, 0이면 이 기능을 끕니다. 새 수치가 기준 아래로 내려오거나 그 창의 초기화 시각에서 5초가 지나면 기다리던 노드가 시작됩니다. 비대화형(claude -p) 세션은 초기화까지 기다릴 수 없습니다. Claude Code가 에이전트가 하나도 돌지 않으면 턴이 끝나고 60초쯤 뒤에 -p 프로세스를 끝내기 때문입니다. 그래서 대기 중인 실행의 노드가 모두 멈추면 남은 노드를 usage limit: 사유로 취소하고 평소처럼 정산 메시지를 보냅니다. 초기화 뒤에 retry로 이어서 실행할 수 있습니다.

자세한 동작은 자동 판단, 전체 옵션은 설정 레퍼런스를 참고하세요.

사용 중 알아둘 점

• 노드가 긴 명령을 실행 중이라면 /clear 대신 /compact를 사용하세요. /clear는 실행 중인 셸을 종료할 수 있습니다.
• 이 세션의 실행이 끝나지 않은 동안에는 노드 작업자, 메인 대화, 그 밖의 하위 에이전트 모두 이름·패턴·포트로 프로세스를 끄는 명령(pkill, killall, pgrep·lsof로 찾은 PID를 kill하거나 반복문으로 kill, ps를 grep·awk로 거른 PID를 kill, fuser -k, taskkill /IM, Stop-Process -Name과 PowerShell 안의 kill -Name 등)을 쓸 수 없습니다. 여러 노드가 한 머신에서 함께 돌기 때문에 다른 노드의 서버를 끌 수 있어서입니다. 직접 띄운 프로세스를 PID로 끄는 것은 허용합니다. 명령은 글자 그대로 읽기 때문에, 커밋 메시지·검색어·heredoc 안에서 pkill 같은 단어가 따옴표나 ; 바로 뒤에 오면 막힐 수 있습니다. 그때는 문구를 바꾸거나 파일을 Write 도구로 쓰면 됩니다.
• 패널에 포커스가 있으면 권한 확인 창에 답하기 전에 Esc로 프롬프트로 돌아가세요.
• 실행 기록, 보고서, 보드는 프로젝트의 .claude/dag/에 저장되며, 기본 보관 기간은 14일입니다. 이 폴더는 자동으로 git에서 제외됩니다.
• 노드의 출력은 잘려서 사라지지 않습니다. 원문 보고서는 파일로 남고 시도마다 따로 보관되며(<node>.attempt-<n>.md), 하위 노드는 의존 노드의 ## Output 앞 4,000자를 받습니다. 그보다 길면 "남은 글자 수와 원문 보고서 파일을 읽으라"는 표시가 붙고, 하위 노드는 그 파일을 읽고 씁니다. Ruling 줄과 재시도 노트는 원문에서 읽으며, 패널·완료 요약·스냅샷처럼 짧게 보여 주는 곳도 몇 자 중 몇 자를 보여 주는지와 원문 보고서 위치를 함께 적습니다.
• 세션이 git worktree에 들어간 뒤(EnterWorktree) 시작한 실행은 노드 실행, verify 검사, 리뷰와 커밋을 모두 그 worktree에서 합니다. 실행 기록은 세션을 시작한 폴더의 .claude/dag/에 남습니다. 실행 도중 세션이 다른 폴더로 옮겨도 실행은 시작한 폴더에서 끝나고, 같은 정의를 다른 worktree에서 다시 시작하면 그 worktree의 새 실행이 됩니다. 실행 도중 그 worktree가 지워지면 다음 노드는 "실행 폴더가 없다"는 분명한 오류로 멈추고 자동 재시도하지 않습니다. worktree를 같은 경로에 다시 만들고 retry하거나 실행을 취소하면 됩니다. worktree 세션에서는 보드의 code_peek와 diff도 그 worktree의 파일과 git을 읽고, 인계 메시지([dag-handoff])는 실행의 worktree 경로를 알려 주며, /dag sessions는 메인 폴더 실행의 상대 writes(예: .)를 worktree 실행과 겹친다고 보지 않습니다.

상세 문서

• 사용법과 설정 레퍼런스: 전체 명령, DAG 정의, 검증, 검토·보안 검토, 복구, 세션 인계, 패널 조작, 보드.
• 개발 안내: 개발 규칙, 검사 명령, DAG 형태 평가, 표시 방식 판단 평가.
• 상태줄 HUD: 플러그인과 별도로 설치하는 상태줄과 Orca 연동.
• 시큐어코딩 시연 키트: 편집 시점 훅, 보안 검토 DAG, 리뷰 수정 라운드를 세 막으로 보여 주는 데모 저장소와 대본.