에이전틱 워크플로우 설계: 실용적인 예시

Source: Dev.to

이전 게시물은 실패 모드—에이전트가 실패하는 지점과 우리가 그들의 출력을 검토할 때 실패하는 지점—에 초점을 맞췄습니다. 이번 후속 글은 진단에서 설계로 전환합니다.

샘플 워크플로우

다음은 이러한 실패 모드를 명시적으로 방지하도록 구조화된 샘플 워크플로우입니다. 이것이 유일한 방법은 아니며 영구적인 해결책을 의미하지도 않습니다. 알려진 위험을 명시적인 제약으로 전환하고 검증을 다시 루프에 끌어들이도록 설계된 실용적인 디자인 중 하나입니다.

Note: 이 게시물은 앞선 분석에 대한 친숙함을 전제로 합니다. 아직 읽지 않으셨다면, 이 워크플로우가 대응하는 실패 모드에 대한 내용은 여기에서 확인할 수 있습니다:
에이전트 워크플로우 설계: 에이전트가 실패하는 지점과 우리가 실패하는 지점.

대상 독자

• Developers new to agentic coding – 에이전시 코딩에 처음인 개발자, 신중하고 구조화된 시작점을 찾는 사람.
• Teams that require reviewable commits – 검토 가능한 커밋이 필요한 팀, 워크플로에 명시적인 검증 게이트가 포함된.
• Enterprise environments – 감사 가능성, 규정 준수 및 낮은 위험의 프로덕션 배포가 필요한 엔터프라이즈 환경.
• Anyone aiming to avoid common AI failure modes – 일반적인 AI 실패 모드를 피하려는 모든 사람, 조기 완료 주장, 무음 테스트 삭제, 얕거나 하드코딩된 구현 등.

의도되지 않은 경우

• 탐색적 해킹
• 그린필드 개인 프로젝트
• 검토 가능성과 책임성이 선택적인 환경

도구가 개선되고 팀이 경험을 쌓음에 따라, 이러한 골격 구조의 대부분을 간소화하거나 제거할 수 있습니다. 이는 일시적인 도움일 뿐, 영구적인 처방이 아닙니다.

핵심 제약

워크플로우는 첫 번째 게시물에 암시되었지만 아직 구체화되지 않은 단일 제약을 중심으로 구축되었습니다:

검증은 언어 모델과 독립적이어야 합니다.

이전 실패 모드는 시스템이 스스로 성공을 판단하도록 허용하는 구조적 문제에 집중되었습니다. 신뢰도 점수, 요약, “완료” 신호가 증거 대신 사용되었습니다. 이 워크플로우는 제안과 검증을 명시적으로 분리합니다.

단계

목표는 신뢰하지만 검증입니다.

최적화 표면 변경

Agentic 시스템은 관찰할 수 있는 것에 대해 최적화한다:

• Green tests
• Plausible diffs
• Explicit completion signals

검토 압박을 받는 인간도 동일하게 행동하는 경향이 있다. 이 최적화 표면을 전환하기 위해 워크플로우:

1. 작업을 작고 검토 가능한 단위로 제한한다.
2. 의도를 명확하고 지속 가능하게 만든다.
3. 완료 주장 전에 독립적인 기계‑검증 가능한 증거를 강제한다.
4. 크고 모호한 diff가 누적되는 것을 방지한다.

독립 검증 제약이 없으면 워크플로우는 이러한 결과를 실질적으로 바꾸지 못한다.

루프 구조

각 작업은 작성된 의도로 시작하며, 이는 다음을 정의합니다:

1. 무엇이 변경되는가
2. 명시적으로 변경되지 않는 것
3. 성공이 어떤 모습인지
4. 검증에 사용할 증거는 무엇인지

이는 의도가 대화 기록에만 남는 것을 방지하고, 무언의 범위 변동을 줄입니다.

계획 단계

에이전트는 코드를 즉시 수정하지 않습니다. 먼저 검토 가능한 명시적 계획을 생성합니다. 그 계획이 승인된 후에 실행이 시작되어, 아키텍처 및 행동 결정이 가시적으로 유지되고 놀라운 차이(diff)를 줄입니다.

범위 제한 루프

각 루프는 좁은 범위로 제한됩니다:

• 하나의 관심사
• 하나의 행동 변화
• 하나의 검증 대상

이는 검토를 인간의 인지 한계 내에 유지하고, 차이가 커짐에 따라 검증에서 타당성으로 전환되는 것을 방지합니다.

독립 검증

완료에는 언어 모델이 아닌 도구가 생성한 증거가 필요합니다, 예를 들어:

• 테스트 실행 결과
• 정적 분석 출력
• 타입‑체커 통과 또는 실패
• 실제 실행의 런타임 트레이스 또는 로그

모델의 설명과 요약은 맥락을 제공할 뿐, 검증을 의미하지 않습니다.

정리 단계

모든 루프는 다음을 수행하는 정리 단계로 끝납니다:

• 임시 골격 코드를 제거합니다
• 불필요한 코드를 제거합니다
• 겹치는 헬퍼를 통합합니다
• 주석을 행동에 맞게 업데이트합니다

정리는 미용 개선이 아니라 정확성의 일부로 간주됩니다; 잔여물은 시간이 지남에 따라 검토 비용과 인지 부하를 누적시킵니다.

저장소 및 문서

저장소에는 동일한 워크플로우의 여러 변형이 포함되어 있으며, 각각은 다른 도구에 맞게 조정되었습니다. 구조적으로 워크플로우는 동일합니다.

• 저장소: (여기에 링크 또는 경로 추가)

각 워크플로우가 문서화하는 내용

• 루프의 단계
• 각 단계에서 에이전트가 수행할 수 있는 작업
• 인간이 검토해야 하는 내용
• 다음 단계로 진행하기 전에 반드시 존재해야 하는 아티팩트

방법론 문서

일반적인 방법론 문서(docs/methodology.md)는 도구에 구애받지 않는 방식으로 워크플로우 형태와 제약 조건을 설명합니다. 단계들을 보여주기 위해 명령형 표기법을 사용하며, 루프의 형태가 정확한 구문보다 중요함을 강조합니다.

# Example of command‑style notation (illustrative only)
phase 1: gather_requirements
phase 2: generate_solution
phase 3: review_by_human
phase 4: finalize_artifacts

위의 자리표시자 예시는 방법론 파일에 사용된 실제 표기법으로 교체하십시오.

제한 사항 및 향후 작업

이 게시물은 의도적으로 워크플로우를 단계별로 설명하지 않습니다; 메커니즘은 저장소에 문서화되어 있습니다. 후속 게시물에서는 하나의 변형을 자세히 살펴보고 여기서 설명한 제약 조건이 실제로 어떻게 적용되는지 보여줄 예정입니다.

워크플로우는 모델을 고치려는 것이 아니라 모델이 작동하는 환경을 변경합니다. 작은 범위, 지속 가능한 의도, 그리고 독립적인 검증은 다음과 같은 영역의 표면을 줄입니다:

• 요구사항이 조용히 사라지는 경우.
• 얕은 구현이 눈에 띄지 않고 통과되는 경우.
• 검토자가 타당성 검사에만 몰입하게 되는 경우.
• 아키텍처 결정이 검토되지 않은 채 넘어가는 경우.

워크플로우는 이러한 실패가 구조가 허용한다면 발생할 것이라고 가정합니다. 그 역할은 이러한 실패를 숨기기 어렵게 만들고, 탐지 비용을 낮추는 것입니다.

채택 가이드

• 기존 워크플로 활용: 이미 강력한 내부 프로세스가 있다면, 이 가이드 중 일부만 채택하면 될 수 있습니다.
• 조기에 시작하고 함정을 피하세요: 에이전트 코딩을 이제 시작한다면, 지금 구조화된 접근 방식을 따르는 것이 나중에 생산 단계에서 비용이 많이 드는 교훈을 피하는 데 도움이 됩니다.

도구가 더 나은 내장 가드레일을 통합함에 따라, 이 권고사항 중 일부는 중복될 수 있습니다. 그때까지도, 신중한 워크플로 설계는 우리가 가진 가장 신뢰할 수 있는 제어 수단입니다.

결론

이 저장소는 복사하고, 수정하고, 결국에는 확장될 수 있도록 설계되었습니다. 이것은 한 가지 방법일 뿐이며, 유일한 방법은 아닙니다.