jacklicn/agent-workflow

워크플로우 생성하기

워크플로우는 "사용자가 하고 싶은 것"을 "무엇을 먼저, 무엇을 다음에, 각 단계에서 어떤 도구를 사용하며, 무엇을 생성할지"로 변환하는 재사용 가능한 프로세스 단위입니다. 이 스킬은 사용자의 요구사항을 docs/workflow/index.md 명세를 준수하는 WORKFLOW.md로 안내합니다.

생성 전에 명세를 읽어보세요: docs/workflow/index.md (3단계 점진적 공개, 그래프-단계 일대일 대응, 프로세스 규칙, 도구 호출 규칙)

사용 시기

• 사용자가 "워크플로우/프로세스/표준화된 흐름을 만들어주세요"라고 요청할 때
• 사용자가 다단계 작업을 설명하며 이를 자동 실행 흐름으로 고정하길 원할 때
• 사용자가 기존 워크플로우를 수정하거나 개선하길 요청할 때
• 사용자가 세션에서 재사용 가능한 다단계 작업을 수행하고 "이 흐름을 고정해주세요"라고 말할 때

생성 과정

1단계: 의도 이해하기

먼저 인터뷰하고 서둘러 파일을 작성하지 마세요:

1. 어떤 작업을 해결하나요? 작업 클래스에 이름을 부여하세요(예: "코드 리뷰", "릴리스 노트").
2. 트리거 시나리오: 사용자가 언제 사용하나요? 트리거 단어(한국어 + 영어)를 수집하세요.
3. 입력과 출력: 어떤 입력(파일/디렉토리/문자열)이 필요한가요? 무엇이 생성되나요(파일/보고서)?
4. 기존 단계: 사용자가 이미 습관적으로 사용하는 흐름이 있나요? 세션 기록에서 도구 호출 순서, 수정 사항, 입/출력 형식을 추출하세요.
5. 경계와 규칙: 수행하지 말아야 할 것은? 산출물은 어디에 저장되나요? 실패는 어떻게 처리하나요?

빠진 정보는 ask_user로 채우고 다음 단계로 넘어가기 전에 확인하세요.

2단계: 순서도 설계하기

mermaid로 실행 순서도를 그리고 그래프-단계 대응 규칙(명세 5.2.1)을 따르세요:

• 모든 노드는 일치하는 단계 섹션이 있어야 하며, 모든 단계는 그래프에 한 번 나타나야 함
• 노드 이름은 단계 이름과 정확히 일치하고 전역적으로 고유해야 함(step-N 접두사는 노드에 표시되지 않아도 됨)
• 결정 노드는 다이아몬드 {}를 사용하며, 반드시 단계 섹션이 있어야 하고 각 분기가 어디로 가는지 Branch로 명시해야 함
• 병렬 단계(분산)는 그래프에서 하나의 노드로 표시
• 그래프는 완전해야 함: 시작, 분기, 종료

단계를 작성하기 전에 그래프를 사용자에게 보여주고 확인을 받으세요.

3단계: WORKFLOW.md 작성하기

<workspace>/workflows/<name>/ 디렉토리와 파일을 생성하세요:

1. 머리말 (1단계 메타데이터):
   • name: 케밥 표기법, 디렉토리 이름과 일치, 소문자/숫자/하이픈만 사용
   • description: 기능 + 사용 시기 + 트리거 단어(한국어와 영어), 트리거 빈도 결정
   • inputs / outputs: 명시적으로 선언, 필수 항목 표시
   • version / tags: 선택 사항
2. 개요: 하는 일, 사용 시기, 생성하는 내용을 한 문단으로 설명
3. 순서도: 2단계와 일관된 mermaid 그래프
4. 단계: 단계당 ### <id>: <name> 섹션, 속성: Tools / Input / Depends on / Action / Check (결정 노드는 Branch, 선택적 when 추가)
5. 프로세스 규칙: 순서 제약, 데이터 의존성, 검증 게이트, 부작용 제약, 최종 상태 확인
6. 도구 호출 규칙: 내장 도구 우선, 스크립트는 대체 수단으로, 읽기는 많이 쓰기는 적게, 경로 규칙

점진적 공개: 긴 테이블은 REFERENCES.md에, 결정적 로직은 scripts/에, 본문은 500줄 미만으로 유지하세요.

4단계: 자가 검증하기

작성 후 명세와 대조하여 확인하세요:

• 그래프-단계 일대일 대응: 그래프에 "고아" 노드가 없고, 섹션에 "고아" 단계가 없음
• 노드 이름이 고유하고 단계 이름과 일치
• 모든 단계에 구체적이고 판단 가능한 Check 있음(예: "파일이 존재하고 비어 있지 않음", "성공 확인"이 아님)
• 도구 이름이 정확함(read_file / exec, "파일 보기"가 아님)
• inputs / outputs가 단계 참조와 일관됨
• 규칙이 실패 처리(재시도/롤백/사용자 질문)를 포함
• 머리말 description이 기능과 트리거 단어를 포함

workflow_list를 사용하여 새 워크플로우가 발견되는지 확인하고, workflow_get <name>으로 읽을 수 있는지 검증하세요.

5단계: 전달하기

사용자에게 알려주세요:

• 워크플로우 이름과 경로
• 트리거 시나리오(어떤 표현이 트리거되는지)
• 흐름 개요(단계 수, 결정/병렬 처리 여부)
• 선택 사항: 실제 테스트 요청 2~3개 제안하여 작동 확인

기존 워크플로우 수정하기

• 먼저 workflow_get <name>으로 현재 내용을 읽으세요
• 머리말의 name과 디렉토리 이름을 변경하지 마세요
• 수정 시 동일한 명세를 따르고, 편집 후 4단계 자가 검증을 실행하세요

참고 사항

• 워크스페이스 workflows/에만 작성하고, 내장된 읽기 전용 워크플로우는 절대 수정하지 마세요. 동일한 이름의 워크스페이스 워크플로우는 내장 워크플로우를 덮어씁니다.
• 하나의 워크플로우는 한 가지 작업 클래스를 해결하며, 관련 없는 흐름을 쌓지 마세요.
• 단계는 3~8개로 유지하고, 그 이상이면 분할하거나 하위 흐름을 참조하세요.
• 악의적이거나 오해의 소지가 있는 지침을 작성하지 마세요. 규칙은 감사 가능해야 합니다.