Dify의 워크플로우 에디터는 직관적이고 다루기 쉽지만, 노드 수가 10개를 넘어가기 시작하면 GUI를 통한 직접 편집만으로는 힘들어집니다. 변경 이력이 남지 않거나, 차분 리뷰 (diff review)를 할 수 없는 등의 문제가 발생하기 때문입니다 (배경에 대한 자세한 이야기는 Zenn 버전에 정리해 두었습니다).

이 기사에서는 해당 Dify 워크플로우를 에스포트(Export)한 YAML을 Claude Code로 편집하는 운용의 구체적인 절차만을 정리합니다. 10~50 노드 규모의 워크플로우에서 실제로 사용하고 있는 진행 방식입니다.

한꺼번에 전체를 생성하게 하면, 생성할 때마다 구성이나 출력의 변동 폭이 커져서 품질이 안정되지 않습니다. 따라서 다음 3단계로 나누어 진행합니다.

Dify의 워크플로우는 GUI 화면에서 「에스포트(Export)」를 통해 YAML(DSL) 파일로 다운로드할 수 있습니다. 이를 Git 리포지토리에 두고 버전 관리를 합니다.

# 에스포트한 YAML을 리포지토리에 배치하고 커밋해 둔다
git add workflow.yml
git commit -m "chore(wf): Dify 워크플로우 YAML 가져오기"

이후에는 이 YAML 파일을 Claude Code가 편집하게 하고, 편집된 YAML을 Dify 측에 다시 임포트(Import)하는 사이클로 진행합니다.

첫 번째 프롬프트에서는 노드의 종류와 연결만 만들게 하고, 각 노드의 내용(프롬프트나 상세 설정)에는 손대지 않게 합니다.

workflow.yml 에 Dify 워크플로우의 뼈대를 만들어 주세요.
조건:
- 노드의 종류와 노드 간의 연결(edges)만 결정할 것
...

여기서 내용까지 깊게 만들게 하지 않는 것이 포인트입니다. 전체 설계와 노드의 세부 사항을 동시에 생성하게 하면, 그만큼 한 번에 결정해야 할 사항이 늘어나고 생성할 때마다 서로 다른 판단이 섞이기 쉬워집니다. 뼈대만으로 범위를 좁힘으로써, 우선 전체 구성을 리뷰할 수 있는 상태를 만듭니다.

뼈대가 완성되면, git diff로 구성을 확인한 후 커밋합니다.

git add workflow.yml
git commit -m "feat(wf): 워크플로우의 뼈대(노드 구성·연결) 생성"

큰 틀에 문제가 없다면, 여기서부터 노드 단위로 내용을 채워 나갑니다. 한 번의 지시로 다루는 노드를 하나로 한정하는 것이 요령입니다.

workflow.yml 의 analyze_data 노드의 프롬프트와 설정만 채워 주세요.
다른 노드의 정의·연결은 일절 변경하지 마세요.

노드마다 지시를 나누면 git diff에 나타나는 변경 범위도 해당 노드에만 국한되어 리뷰하기 쉬워집니다. 1노드 = 1커밋 정도의 입도로 유지하면, 나중에 "어느 노드를 언제·어떻게 바꿨는지"를 git log로 추적할 수 있습니다.

git add workflow.yml
git commit -m "feat(wf): analyze_data 노드의 프롬프트 조정"

50 노드 규모의 워크플로우라면 이 공정이 꽤 여러 번 반복되겠지만, 기계적으로 "1노드씩, 나머지는 건드리지 않기"를 철저히 지키기만 하면 시간이 걸리더라도 품질은 안정됩니다.

모든 노드의 튜닝이 끝나면, 마지막으로 변수 참조의 정합성만을 모아서 체크합니다. 노드 단위 작업 중에는 놓치기 쉬운 포인트이므로 독립된 공정으로 분리합니다.

workflow.yml 전체를 확인해 주세요.
다음 관점에서 변수 참조의 불일치가 있다면 목록으로 만들어 주세요.
- 참조하고 있는 변수가 실재하는 노드의 출력 키를 가리키고 있는가 (미연결·존재하지 않는 참조가 없는가)
...

실제로 이 공정에서 타입이 일치하지 않는 변수 참조나, 리네임(Rename) 후에 참조가 업데이트되지 않은 곳이 여러 군데 발견되었습니다. 노드 단위의 튜닝에서는 한 번에 한 노드씩만 보고 있기 때문에, 이러한 "노드를 가로지르는 정합성의 붕괴"는 이 단계까지 남아 있는 경우가 많습니다.

불일치가 발생한 경우에는 지적된 부분만 수정하게 하고 다시 체크를 돌립니다.

git add workflow.yml
git commit -m "fix(wf): 변수 참조의 타입 불일치·미연결 수정"

지금까지의 변경 사항을 Dify 측에 다시 임포트하고, 실제로 실행하여 동작을 확인합니다. GUI상의 설정과 YAML의 내용이 어긋나지 않도록, 편집은 YAML 측에서만 수행하며 GUI에서는 직접 수정하지 않는 것을 철저히 지키고 있습니다.

• Dify 워크플로우는 GUI에서 직접 편집하지 않고, 내보낸(export) YAML을 Claude Code로 편집한 후 다시 임포트한다.
• 한꺼번에 전체를 생성하게 하지 않고, ① 큰 틀(노드 구성·연결) → ② 노드 단위의 튜닝(tuning) → ③ 변수의 정합성 체크,의 3단계로 나누어 진행한다.
• 각 단계 단위로 커밋(commit)해 두면, git diff를 통한 리뷰나 git log를 통한 변경 추적이 용이하다.
• 변수의 정합성 체크는 노드 단위 작업만으로는 모두 잡아낼 수 없으므로, 마지막에 독립된 공정으로 실시한다.

왜 GUI를 사용하지 않고 이러한 운영 방식을 택했는지, 처음에 한꺼번에 생성했다가 실패했던 경위에 대해서는 Zenn 버전에 작성해 두었습니다.