workflow-patterns

workflow-patterns 스킬 개요

workflow-patterns가 실제로 도와주는 일

workflow-patterns 스킬은 구현 작업을 엄격한 테스트 주도 순서로 수행하게 해주는 프로세스 중심 스킬입니다. Conductor 스타일의 작업 전달 방식에 맞춰 설계되어 있으며, 다음 예정 작업 선택, plan.md에 상태 표시, 실패하는 테스트를 먼저 작성, 작은 단위로 구현 진행, 체크포인트에서 검증, 작업 상태에 맞춘 커밋 정렬까지 일관된 흐름을 따릅니다. 에이전트가 곧바로 코드부터 작성하는 대신, 규율 있는 전달 패턴을 따르게 하고 싶다면 workflow-patterns의 용도는 바로 여기에 있습니다.

어떤 경우에 workflow-patterns 스킬이 잘 맞나

이 workflow-patterns skill은 이미 작업 계획을 태스크 단위로 관리하고 있고, AI 에이전트의 실행 신뢰성을 높이고 싶은 팀이나 1인 개발자에게 잘 맞습니다. 특히 아래가 중요할 때 유용합니다.

• 단계별 작업 순서를 유지하고 싶을 때
• red-green-refactor 흐름을 강제하고 싶을 때
• 진행 상황을 plan.md에 남기고 싶을 때
• 상태 커밋과 구현 커밋을 분리하고 싶을 때
• 작업 완료 선언 전에 검증을 반드시 돌리고 싶을 때

저장소에 이미 계획 산출물과 테스트가 있다면, 이 스킬은 단순한 “이 기능 구현해줘” 프롬프트보다 훨씬 큰 가치를 냅니다.

진짜 해결해야 하는 일

대부분의 사용자는 TDD 이론을 원하는 것이 아닙니다. 원하는 것은 계획된 작업 하나를 받아서 워크플로 제어를 건너뛰지 않고 끝내는 에이전트입니다. 실제로 해결하려는 일은 이것입니다. 체크박스 기반 작업 목록을, 테스트 누락은 줄이고 인수인계 모호성은 낮추며 진행 추적은 더 명확하게 만드는 반복 가능한 구현 루프로 바꾸는 것.

일반적인 코딩 프롬프트와 workflow-patterns가 다른 점

일반 프롬프트는 보통 코드가 먼저고 프로세스가 나중입니다. workflow-patterns는 이 순서를 뒤집습니다. 에이전트에 다음과 같은 명시적 체크포인트가 있는 작업 생명주기를 제공합니다.

1. 순서대로 다음 대기 작업을 고른다
2. 진행 중으로 표시한다
3. 실패하는 테스트를 작성한다
4. 테스트가 통과할 때까지 구현한다
5. 리팩터링한다
6. 검증을 실행한다
7. 작업 상태를 업데이트하고 적절히 커밋한다

가장 큰 리스크가 코드 생성 자체가 아니라 통제되지 않은 실행이라면, 이 구조는 매우 중요합니다.

설치 전에 알아둘 중요한 한계

이 스킬은 의도적으로 범위가 좁습니다. 프레임워크별 구현 규칙, 테스트 라이브러리, 저장소 전용 명령어는 제공하지 않습니다. 그런 부분은 사용자가 직접 제공해야 합니다. 프로젝트에 plan.md가 없거나, 테스트 커버리지가 약하거나, 잘게 나눈 규율 있는 커밋을 선호하지 않는다면 workflow-patterns for Workflow Templates는 다소 경직되게 느껴질 수 있습니다.

workflow-patterns 스킬 사용법

workflow-patterns 스킬 설치 방법

wshobson/agents 저장소에서 설치합니다.

npx skills add https://github.com/wshobson/agents --skill workflow-patterns

설치 후에는 에이전트가 자유롭게 구현하도록 두는 대신, 저장소의 작업 생명주기를 따르게 하고 싶을 때 호출하면 됩니다.

이 스킬이 있는 위치와 먼저 읽어야 할 파일

스킬 위치는 다음과 같습니다.

plugins/conductor/skills/workflow-patterns/SKILL.md

가장 먼저 SKILL.md를 읽으세요. 이 스킬에서는 해당 파일이 단일한 기준 문서이며 전체 워크플로가 모두 들어 있습니다. 별도의 보조 폴더는 없으므로, 실제 도입에서 핵심은 이 순서를 이해하고 자신의 저장소 관례에 맞게 적용하는 것입니다.

workflow-patterns가 잘 작동하려면 필요한 입력

이 스킬은 실행 맥락을 구체적으로 줄수록 훨씬 유용해집니다.

• plan.md 경로
• 현재 단계 또는 마일스톤
• 검토할 정확한 작업 ID, 또는 다음 [ ] 항목을 선택해도 된다는 권한
• 테스트 명령어
• lint/typecheck/build 명령어
• 브랜치 또는 커밋 정책
• “생성 파일은 수정하지 말 것” 같은 저장소 제약

이 정보가 없으면 에이전트는 프로세스는 이해해도, 프로젝트에서 무엇으로 검증해야 하는지 추측하게 될 수 있습니다.

workflow-patterns를 제대로 호출하는 최소 프롬프트

실제로 쓸 수 있는 최소 시작 프롬프트는 다음과 같습니다.

Use the workflow-patterns skill.

Project plan: docs/plan.md
Follow tasks in order and do not skip phases.
Select the next pending [ ] task, mark it [~], and keep status updates separate from implementation commits.
Use TDD: write failing tests first, then implement, then refactor.
Verification commands:
- pytest
- ruff check .
- mypy .
When complete, update the task to [x] only if verification passes.

이 정도만 해도 “다음 기능 구현해줘”보다 훨씬 낫습니다. 작업 출처, 순서, 검증, 완료 기준이 모두 포함되기 때문입니다.

거친 목표를 강한 workflow-patterns 프롬프트로 바꾸는 법

약한 목표:

Implement the next task with workflow-patterns.

더 강한 목표:

Use the workflow-patterns skill for docs/plan.md.

Current target phase: Phase 2 only.
Select the next unchecked task in order.
Before coding, change that task from [ ] to [~].
Write failing tests covering happy path, edge cases, and one error path.
Use these commands:
- npm test -- --runInBand
- npm run lint
- npm run typecheck
Do not modify unrelated tasks.
When all checks pass, refactor if needed, update plan.md to [x], and summarize what changed.

더 강한 버전은 도입 시 가장 흔한 리스크를 줄여줍니다. 에이전트가 워크플로는 알지만, 로컬 제약을 몰라서 빗나가는 문제를 줄일 수 있습니다.

실제 workflow-patterns 작업 생명주기

핵심적인 workflow-patterns usage 패턴은 다음과 같습니다.

1. plan.md를 확인한다
2. 현재 단계에서 다음 대기 작업을 고른다
3. 해당 작업을 [~]로 표시한다
4. 그 상태 변경은 커밋하거나 최소한 분리해 둔다
5. 실패하는 테스트를 작성한다
6. 통과에 필요한 최소 변경만 구현한다
7. 안전하게 리팩터링한다
8. 검증을 실행한다
9. 작업을 [x]로 표시한다
10. 최종 커밋 메모와 요약을 정리한다

이 점이 중요한 이유는, 이 스킬이 단순 코드 수정이 아니라 상태 전이를 중심으로 설계되어 있기 때문입니다.

plan.md 품질이 출력 품질에 직접 영향을 주는 이유

이 스킬의 결과물은 실행하는 계획의 품질만큼만 좋아집니다. “인증 흐름 개선”처럼 모호한 작업 문구는 테스트 대상도 모호해지고 완료 판단도 약해집니다. 좋은 작업은 테스트 가능할 정도로 구체적이어야 합니다.

• 영향받는 파일 또는 모듈
• 기대 동작
• 오류 조건
• 인수 기준
• 이전 작업에 대한 의존성

plan.md가 빈약하다면, workflow-patterns guide를 평가하기 전에 먼저 그 계획부터 보강하는 편이 맞습니다.

검증 명령어를 다루는 방법

이 스킬은 검증 프로토콜을 강조하지만, 어떤 명령을 써야 하는지는 기본으로 알지 못합니다. 항상 정확한 명령과 실패 처리 정책을 함께 제공해야 합니다. 예를 들면:

Verification must pass before task completion:
- cargo test
- cargo clippy -- -D warnings
- cargo fmt --check

If any verification step fails, do not mark the task complete.

이렇게 해야 에이전트가 부분 테스트만 하고도 작업이 끝났다고 말하는 흔한 실패를 막을 수 있습니다.

커밋 처리와 상태 추적

workflow-patterns install의 실무적인 장점 중 하나는 AI를 사용할 때 저장소 위생이 더 좋아진다는 점입니다. 이 스킬은 상태 업데이트와 구현 작업을 명시적으로 다른 이벤트로 취급합니다. 다음이 중요할 때 특히 도움이 됩니다.

• 버전 관리에서 작업 진행 상황이 눈에 보일 때
• 리뷰가 더 깔끔해질 때
• 워크플로 메타데이터와 코드 롤백을 쉽게 나누고 싶을 때
• 작업이 정말 진행 중인지 완료인지 모호함을 줄이고 싶을 때

팀에서 별도 커밋을 원하지 않는다면, 처음부터 그렇게 말하고 커밋은 나누지 않되 상태 전이는 유지해 달라고 요청하면 됩니다.

워크플로를 문자 그대로 따르기보다 조정해야 할 때

이 순서는 교조적인 규칙집이 아니라 제어 시스템으로 쓰는 것이 좋습니다. 환경이 다르면 다음처럼 조정하세요.

• monorepo는 패키지 범위 테스트 명령이 필요할 수 있습니다
• 레거시 저장소는 characterization test가 먼저일 수 있습니다
• 프로토타입은 커밋 수를 줄이되 [ ] → [~] → [x]는 유지하는 편이 낫습니다
• hotfix는 리팩터링 범위를 더 좁게 잡는 것이 타당할 수 있습니다

핵심은 리스크를 줄이는 체크포인트, 특히 테스트 선행과 명시적 검증을 유지하는 것입니다.

workflow-patterns 스킬 FAQ

workflow-patterns는 Conductor 사용자만 위한 스킬인가?

아닙니다. 다만 Conductor 스타일의 계획 관리와 TDD 영향을 분명히 받았습니다. 동등한 계획 파일, 작업 순서, 검증 루틴이 있다면 그 생태계 밖에서도 workflow-patterns를 사용할 수 있습니다. 반대로 이런 기반이 없으면 이 스킬의 장점은 상당 부분 사라집니다.

기능 작업에서는 일반 프롬프트보다 더 나은가?

그렇습니다. 특히 핵심 문제가 구현 능력이 아니라 실행 규율일 때 더 그렇습니다. 일반 프롬프트도 그럴듯한 코드를 만들 수는 있지만, 작업 순서, 진행 상태 업데이트, 테스트 우선 동작을 자주 건너뜁니다. 속도보다 일관성과 추적 가능성이 중요하다면 workflow-patterns usage가 더 적합합니다.

workflow-patterns는 초보자도 쓰기 쉬운가?

보통 수준입니다. 프로세스 자체는 따라가기 쉽지만, 초보자는 다음이 부족하면 막히기 쉽습니다.

• 명확한 plan.md
• 실패하는 테스트를 먼저 쓰는 데 대한 자신감
• 프로젝트별 검증 명령어
• 작고 리뷰 가능한 커밋에 대한 이해

TDD가 익숙하지 않다면, 단계 전체를 한 번에 처리하려 하지 말고 범위가 명확한 작업 하나로 시작하는 편이 좋습니다.

workflow-patterns 스킬을 쓰지 말아야 할 때는?

다음과 같다면 건너뛰는 편이 낫습니다.

• 작업 계획을 유지하지 않을 때
• 통제된 실행보다 탐색적 코딩이 더 필요할 때
• 저장소에 테스트 인프라가 거의 없거나 전혀 없을 때
• 에이전트에게 대기 중인 작업 완료보다 아키텍처 브레인스토밍을 기대할 때
• 상태 관리와 검증 오버헤드를 들일 만큼 큰 작업이 아닐 때

이런 경우에는 더 가벼운 구현 스킬이나 직접 프롬프트가 더 잘 맞을 수 있습니다.

workflow-patterns에 저장소별 명령어 또는 자동화가 포함되어 있나?

아니요. 저장소 기준으로 보면 이 스킬은 보조 스크립트나 규칙 파일이 있는 패키지라기보다, SKILL.md 중심의 문서에 가깝습니다. 핵심 가치는 실행 패턴에 있으며, 실제 운영 세부사항은 사용자가 제공해야 합니다.

불완전하거나 어수선한 계획에도 workflow-patterns가 도움이 되나?

부분적으로만 그렇습니다. 순서와 상태 전이는 강제할 수 있지만, 모호한 백로그 항목에서 좋은 인수 기준까지 만들어내지는 못합니다. 작업 정의가 약하면 강한 결과를 기대하기 전에 계획부터 보강해야 합니다.

workflow-patterns 스킬 개선 방법

workflow-patterns에 더 강한 작업 정의를 제공하기

결과를 가장 빨리 개선하는 방법은 작업 문구를 업그레이드하는 것입니다. 이 스킬에 적합한 작업은 동작, 제약, 완료 기준을 함께 담고 있어야 합니다. 예를 들면:

약한 예:

- [ ] Improve validation

더 나은 예:

- [ ] Task 2.1: Reject invalid email formats in user registration, return 400 with field-level error, and add tests for valid, invalid, and missing email cases

이 한 가지 변화만으로도 에이전트는 red 테스트, 구현 범위, 검증 기준을 훨씬 선명하게 잡을 수 있습니다.

일반적인 “run checks” 대신 정확한 명령어를 주기

workflow-patterns usage에서 생기는 많은 실패는 검증 조건이 불충분하게 주어졌기 때문입니다. “테스트와 린트 실행” 같은 문구 대신 정확한 명령과 필요한 환경 정보를 쓰세요. 테스트에 서비스, fixture, 패키지 필터가 필요하다면 그것도 함께 포함해야 합니다.

작업 순서를 얼마나 엄격히 지킬지 에이전트에 명확히 알리기

이 스킬은 기본적으로 현재 단계 안에서 순차 실행을 가정합니다. 실제 워크플로에 예외가 허용된다면 그 점을 분명히 적어야 합니다. 그렇지 않으면 에이전트가 필요 이상으로 많이 건너뛰거나, 반대로 유용한 작업도 거부할 수 있습니다. 정책이 명확할수록 신뢰성이 높아집니다.

Do not skip tasks unless blocked by missing infrastructure.
If blocked, stop and report the blocker instead of jumping ahead.

프로젝트가 레거시 중심이라면 저장소별 TDD 가이드를 추가하기

성숙한 저장소에서는 순수한 red-green-refactor를 그대로 적용하기 어렵기도 합니다. 테스트 하네스가 느리거나 아키텍처가 복잡하게 얽혀 있다면, 에이전트가 이 패턴을 어떻게 해석해야 할지 알려주세요.

• 리팩터링 전에는 characterization test를 우선한다
• 수정한 모듈 범위로만 스코프를 제한한다
• 같은 작업 안에서 광범위한 정리는 피한다
• 이미 알려진 flaky test는 별도로 기록한다

이렇게 해야 workflow-patterns가 교조적이지 않고 실제적인 방식으로 작동합니다.

흔한 실패 패턴을 미리 막기

가장 흔한 문제는 예측 가능합니다.

• 모든 검증이 끝나기 전에 작업을 완료로 표시하는 것
• 구현 후에 테스트를 작성하는 것
• 한 번에 여러 작업을 수정하는 것
• 진행 중 상태인 [~]를 건너뛰는 것
• 워크플로 메타데이터와 기능 작업을 구분 없이 섞는 것

이 부분이 팀에 중요하다면 프롬프트에서 직접 못 박아 두는 편이 좋습니다.

작업 종료 시 구조화된 보고를 요청하기

일상적인 작업에서 이 스킬을 더 유용하게 쓰려면, 각 작업을 끝낼 때 에이전트가 짧은 보고서 형태로 마무리하도록 요청하세요.

• 선택한 작업
• 추가하거나 수정한 테스트
• 구현 요약
• 검증 결과
• plan 파일의 상태 변경
• blocker 또는 후속 작업

이렇게 하면 workflow-patterns guide의 출력이 리뷰어와 다음 세션 모두가 신뢰할 수 있는 형태가 됩니다.

첫 실행이 어색해도 스킬을 버리지 말고 입력을 먼저 다듬기

첫 결과가 마음에 들지 않는다고 해서 곧바로 workflow-patterns skill 자체가 약하다고 판단할 필요는 없습니다. 대부분의 경우 문제는 실행 맥락이 부족했다는 데 있습니다. 입력은 다음 순서로 개선하세요.

1. 더 명확한 작업 문구
2. 정확한 검증 명령어
3. 허용 범위와 파일 제약
4. 커밋/상태 정책
5. blocker 처리 규칙

이 정보가 갖춰지면, 이 스킬은 훨씬 더 통제된 방식으로 신뢰도 높은 작업 실행을 만들어낼 가능성이 큽니다.