Claude Code 워크플로우와 하네스 엔지니어링, 마이크로서비스 환경에서 어떻게 써먹을까

By on June 6, 2026

들어가며 — 왜 또 “하네스”와 “워크플로우”인가

AI 코딩 도구 이야기가 나오면 흔히 “프롬프트 엔지니어링”이 먼저 언급됩니다.

하지만 실제로 팀 단위에서 사용해 보면 중요한 것은 프롬프트 자체보다 워크플로우와 실행 환경 설계입니다.

Anthropic에서 이야기하는 하네스 엔지니어링(Harness Engineering) 은 처음 들으면 다소 추상적으로 느껴질 수 있습니다. 하지만 Claude Code의 동적 워크플로우(Dynamic Workflow)를 경험해 보면, 이 개념이 실제 개발 프로세스 안으로 내려온 것을 확인할 수 있습니다.

이 글은 이전 글 2026년 AI 에이전트의 핵심, 하네스 엔지니어링 의 후속편입니다. 이전 글이 “하네스란 무엇인가”였다면, 이번 글은 “그래서 실무에 어떻게 적용하는가”입니다.

이번 글에서는 여러 마이크로서비스 레포지토리를 운영하는 백엔드 관점에서,

하네스 엔지니어링은 무엇인지
Claude Code 워크플로우는 무엇인지
둘을 어떻게 함께 설계해야 하는지

정리해 보겠습니다.

하네스 엔지니어링 한 줄 정의

하네스 엔지니어링을 짧게 정의하면 다음과 같습니다.

AI 모델 바깥에 있는 실행 시스템 전체를 설계하는 일

여기서 말하는 실행 시스템은 다음을 포함합니다.

어떤 문서를 기준으로 작업할 것인가
어떤 계획을 세울 것인가
어떤 도구를 사용할 것인가
어떻게 실패를 감지할 것인가
언제 사람의 승인을 받을 것인가
어떤 피드백 루프를 만들 것인가

즉,

문서
코드 저장소
CI/CD
테스트
모니터링
권한 관리
운영 프로세스

전체를 포함하는 개념입니다.

중요한 점은 하네스 엔지니어링이 프롬프트 엔지니어링의 상위 개념이라는 것입니다.

좋은 프롬프트는 여전히 중요하지만,

“좋은 프롬프트를 어디서, 언제, 어떤 규칙 아래 실행할 것인가”

를 설계하는 것이 하네스 엔지니어링의 관심사입니다.

특히 Anthropic이 강조하는 부분은 Evaluation(평가) 입니다.

AI가 작업을 수행하는 것보다 더 중요한 것은,

결과를 어떻게 평가할 것인지
실패를 어떻게 감지할 것인지
다음 실행에 어떻게 반영할 것인지

를 정의하는 것입니다.

Claude Code 워크플로우가 바꿔 놓은 메커니즘

초기 Claude Code는

코드 탐색
파일 수정
명령 실행

정도의 AI 페어 프로그래머에 가까웠습니다.

하지만 최근에는 동적 워크플로우(Dynamic Workflow) 개념으로 발전하고 있습니다.

1) 먼저 계획을 세운다

Claude는 단순히 파일을 수정하는 것이 아니라 먼저,

현재 레포 탐색
요구사항 분석
작업 분해
영향도 분석
실행 계획 수립

을 수행합니다. 이후 그 계획에 따라 실제 작업을 진행합니다.

2) 병렬 에이전트를 활용한다

대규모 리팩토링이나 코드 감사 작업에서는,

코드 분석
테스트 검토
문서 검토
영향도 분석

등을 여러 에이전트에 분산시켜 병렬로 수행할 수 있습니다.

결과적으로 사람이 직접 여러 체크리스트를 수행하던 작업을 자동화할 수 있게 됩니다.

3) 컨텍스트를 관리한다

동적 워크플로우의 또 다른 특징은 컨텍스트 관리입니다.

Claude는 전체 코드베이스를 한 번에 읽는 것이 아니라,

필요한 정보를 탐색하고
요약하고
다음 단계의 작업에 활용

하는 방식으로 동작합니다.

따라서 워크플로우 품질은 모델 성능뿐 아니라,

문서 구조
디렉터리 구조
CLAUDE.md
아키텍처 문서

의 품질에도 크게 영향을 받습니다.

결국 Claude Workflow는 하네스를 대체하는 것이 아닙니다.

Claude Workflow는 하네스 내부의 실행 계층을 자동화하는 역할에 가깝습니다.

예전에는 사람이 하네스를 설계하고 Claude는 그 안에서 작업만 수행했다면, 지금은 Claude가 하네스 내부의 일부 실행 절차를 스스로 계획하고 수행할 수 있게 된 것입니다.

하네스 vs Claude 워크플로우

관점	하네스 엔지니어링	Claude Code 워크플로우
초점	AI 밖 전체 실행 시스템	코드 작업 중심 자동화
범위	문서, CI, 모니터링, 권한, 피드백 루프	코드 탐색, 수정, 테스트
추상도	아키텍처/프로세스	구현/실행
역할 분리	플래너·실행기·평가자·사람	계획·실행·검증 통합
적용 범위	모델 독립적	Claude Code 중심
목표	장기 품질, 비용, 리스크 관리	개발 생산성 향상

한 문장으로 정리하면,

하네스 엔지니어링은 철학과 아키텍처 프레임워크이고, Claude Workflow는 그 프레임워크 일부를 코드 작업 영역에 구현한 실행 엔진입니다.

마이크로서비스(다중 레포) 환경 레퍼런스 아키텍처

제가 생각하는 이상적인 구조는 크게 세 계층입니다.

서비스 레포 내부 실행 계층
Control Repo 기반의 중앙 규칙 계층
Cross-repo 검증 및 오케스트레이션 계층

[엔지니어의 요청]
      |
      v
[Control Repo / Architecture Repo]
  - standards/
  - service-catalog.yaml
  - api-contracts/
  - workflow-prompts/
  - decision-log/
      |
      +-------------------------+-------------------------+
      |                         |                         |
      v                         v                         v
[service-auth repo]       [service-order repo]     [service-payment repo]
  CLAUDE.md                 CLAUDE.md                CLAUDE.md
  /commands                 /commands                /commands
  tests/contract            tests/contract           tests/contract
  ci quality gate           ci quality gate          ci quality gate
      |                         |                         |
      +----------- cross-repo validation layer ----------+
                          |
                          v
                [Integration / Contract / E2E]

서비스 레포에 들어가는 것

각 서비스 레포에는 최소한 다음이 존재하는 것이 좋습니다.

CLAUDE.md

서비스 책임
도메인 경계
외부 의존성
필수 테스트
운영 규칙

docs/domain.md

Aggregate
트랜잭션 경계
이벤트 흐름

.claude/commands

반복되는 작업 자동화

tests/contract

API 계약 검증
이벤트 계약 검증

목표는 다음과 같습니다.

Claude가 처음 들어와도 사람처럼 레포를 이해하고 움직일 수 있게 만드는 것

Control Repo가 하는 일

Control Repo는 조직의 아키텍처 지식을 중앙 집중화하는 공간입니다.

service-catalog.yaml

서비스 이름
레포 주소
담당 조직
서비스 오너
SLA
주요 의존 서비스

services:
  - name: payment
    owner: payments-team
    repository: github.com/company/payment
    sla: tier-1

api-contracts

OpenAPI
이벤트 스키마
버전 정책

workflow-prompts

장애 분석
마이그레이션
코드 감사
기능 구현

decision-log

ADR
아키텍처 결정
기술 선택 이유

여기서 중요한 원칙은 다음입니다.

크로스 레포 변경은 Control Repo에서 시작한다.

즉, 코드 수정보다 먼저

어떤 서비스가 영향 받는지
어떤 순서로 변경할지
어떤 검증이 필요한지

를 분석해야 합니다.

실제로 쓰는 명령어·프롬프트 예시

1) 레포 온보딩

/init

이 레포는 주문 서비스입니다.

src, test, 빌드 설정을 읽고
아래 내용을 CLAUDE.md에 정리해줘.

1. 서비스 책임과 도메인 경계
2. 주요 외부 의존성
3. 로컬 실행 방법
4. 필수 테스트 목록
5. 변경 시 체크리스트

2) 기능 구현 계획 수립

/plan

주문 생성 API에
idempotency key 검증을 추가하는 작업 계획을 세워줘.

요구사항:
- 동일 키 재요청 시 기존 결과 반환
- 트랜잭션 경계 유지
- 외부 결제 호출 전후 예외 처리 분리

산출물:
- 영향 파일 목록
- 단계별 변경 계획
- 테스트 전략
- 롤백 전략

계획이 만족스러우면,

좋아.
방금 세운 계획대로 구현해줘.

테스트를 실행하고,
실패가 있으면 수정까지 진행해.

3) 레포 감사 및 리팩토링

Use a workflow to analyze this repository for retry,
timeout, and transaction boundary issues.

범위:
- service layer
- Kafka consumer
- Kafka producer
- 외부 API client

산출물:
1. 잠재 문제 목록
2. 코드 근거
3. 수정 필요 항목
4. 리팩토링 권장 항목
5. 우선순위 제안

또는,

Use a workflow to migrate this service
from ad-hoc retry handling
to a unified retry policy.

요구사항:
- 공통 retry 모듈 도입
- 기존 retry 로직 수집
- 테스트 추가
- 롤아웃 체크리스트 작성

4) Cross-repo 변경 분석

Use a workflow to identify every repository
impacted by changing payment status enum.

요구사항:

1. 영향 받는 서비스 식별
2. API 변경 포인트 정리
3. 이벤트 변경 포인트 정리
4. 구현 순서 제안
5. 롤백 전략 작성

주의:
이번 단계에서는 코드를 수정하지 말고
영향도 분석과 계획만 수행해.

특히 마이크로서비스에서는

영향도 분석
배포 순서
Backward Compatibility

까지 함께 계획해야 합니다.

예를 들어,

Consumer 먼저 배포
Producer 나중 배포
트래픽 전환
레거시 제거

같은 전략을 미리 정의하는 것이 중요합니다.

정리 — 엔지니어가 설계해야 할 것 vs Claude에게 맡겨도 되는 것

엔지니어가 설계해야 하는 것

서비스 경계
트랜잭션 경계
API 계약
버전 정책
워크플로우 종류
실패 감지 전략
자동 복구 범위
문서 구조
Control Repo 구조

Claude에게 맡길 수 있는 것

코드 수정
리팩토링
테스트 작성
반복 감사 작업
설계 초안 작성
PR 설명 작성
릴리스 노트 작성
워크플로우 단계 실행

결국 중요한 것은 프롬프트 자체가 아닙니다.

Claude Code가 강력해질수록 중요한 것은,

Claude가 어떤 문서를 읽고, 어떤 규칙을 따르며, 어떤 검증을 통과해야 하는지를 설계하는 능력입니다.

이전에는 사람이 하네스를 설계하고 Claude는 그 안에서만 움직였습니다. 이제는 Claude가 하네스 내부의 일부 실행 절차를 스스로 계획하고 수행할 수 있게 되었습니다.

따라서 앞으로 엔지니어에게 필요한 역량은 단순히 “프롬프트를 잘 쓰는 사람”이 아니라,

좋은 하네스를 설계하는 시스템 아키텍트

에 더 가까워질 것입니다.