클로드 코드로 만든 주식 분석 리포트: 하네스 분석하기

2. 에이전트 구성

자, 그러면 각 에이전트는 어떻게 구성해야 할까요?

각 에이전트는 앞 단계가 남긴 파일을 입력으로 읽고, 자신의 결과를 다음 단계가 읽을 파일로 남깁니다. Planner가 plan/<slug>.md를 쓰면 Research Generator가 그것을 읽어 research/<slug>.md를 만들고, Lecture Generator가 다시 그 둘을 읽어 drafts/<slug>.md를 작성하는 식입니다.

Planner

Planner는 사용자의 자연어 요청을 plan/<slug>.md로 바꾸는 기준 문서 작성자입니다. 이 에이전트는 주제를 정리하는 수준을 넘어 후속 단계가 따라야 할 데이터 조건과 검증 기준까지 지정합니다. Planner의 역할은 ‘무엇을 만들지’뿐만 아니라 ‘어떤 근거로 검증할지’까지 먼저 고정하는 것입니다. Planner가 확정하는 주요 항목은 다음과 같습니다.

slug / topic, request / output_type / audience / ticker / period_start, period_end / chart_required / price_data_source: yfinance / price_data_interval: 1d / assumptions / 리서치 질문 / 데이터 요구 사항 / 리포트 개요 / 차트 계획 / Hero 이미지 방향 / 리뷰 기준 / 리스크와 제약

Research Generator

Research Generator는 plan/<slug>.md를 읽고 research/<slug>.md를 작성합니다. 이 파이프라인에서 가장 강화된 단계입니다. 종목이 포함된 경우 Research Generator는 다음을 수행합니다.

• yfinance 기준 ticker와 기간을 확인합니다.
• 가격 데이터는 1일봉(interval=1d) 기준으로 다룹니다.
• 종목별 최신 뉴스 최소 100건을 수집합니다.
• 뉴스 100건을 날짜, 매체, 제목, 핵심 이슈, 가격·수급·리스크 해석으로 분류합니다.
• 한국 상장 종목은 가능하면 토스증권 뉴스와 투자자별 매매 동향을 참고합니다.
• 사용한 API 또는 페이지 URL을 sources와 output/assets/* 원자료 JSON에 남깁니다.
• 항목별 URL이 없으면 임의로 조작하지 않고 fallback 여부를 명시합니다.

Lecture Generator

Lecture Generator는 plan과 research를 읽어 drafts/<slug>.md를 만듭니다. 이 단계의 목표는 리서치 메모를 독자가 이해할 수 있는 리포트 원고로 바꾸는 것입니다. draft 규칙은 다음을 요구합니다.

• frontmatter에 ticker, period_start, period_end, plan_source, research_source를 둡니다.
• 가격 차트가 필요한 경우 직접 숫자를 임의 삽입하지 않고 price-chart 블록을 선언합니다.
• 숫자와 사실 주장은 research 출처와 연결합니다.
• 투자 권유, 수익 보장, 매매 지시처럼 보이는 표현을 피합니다.
• 최신 뉴스 100건 중 시간 순 최신 5건을 별도 블록으로 요약합니다.
• 최신 뉴스 5건의 제목은 클릭 가능한 링크여야 합니다.

예시 차트 블록은 다음과 같습니다.

이 구조 덕분에 초안 작성자는 가격 데이터를 꾸며 쓰지 않고, build 단계가 실제 yfinance 데이터를 사용하여 차트를 생성합니다. 작성과 데이터 처리를 분리하는 단순한 장치이지만, 잘못된 가격표가 본문에 섞이는 사고를 원천적으로 막습니다.

Image Generator

Image Generator는 plan, research, draft를 모두 읽고 GPT의 image gen 스킬을 이용하여 3개의 이미지 후보를 만듭니다. 이미지 규칙은 이미지가 단순 장식이 아니라 리포트 메시지의 시각 요약이어야 한다고 봅니다. 필수 산출물은 다음과 같습니다.

최종 HTML은 선택된 hero 이미지 한 장만 사용합니다. 선택 정보가 없으면 build 단계는 완료로 취급하지 않습니다.

3. 리뷰 에이전트

리뷰 단계는 이 시스템에서 가장 중요한 안전장치입니다. 메인 세션이 직접 “괜찮다”고 판단하지 않고, 별도 관점의 리뷰 에이전트를 거쳐 검토합니다. 이때 리뷰 에이전트들은 모두 메인 세션과 분리된 다른 세션에서 독립적으로 실행됩니다. 같은 모델을 쓰더라도 세션이 다르면 사고의 관성이 끊어지고, 처음 보는 사람의 시선이 되살아나기 때문입니다.

여기에 더해 클로드 코드 기반의 리뷰뿐만 아니라 코덱스의 리뷰까지 함께 활용합니다. 같은 결과물을 서로 다른 모델로 한 번 더 보게 해서 교차 검증을 거치는 셈입니다. 한 모델이 놓친 부분을 다른 모델이 잡아낼 가능성을 높이는 장치입니다.

fact-checker

fact-checker는 사실성 담당 에이전트입니다. 즉, fact-checker는 ‘문장이 그럴 듯한가’가 아니라 ‘근거 체인이 끊기지 않았는가’를 봅니다. 주요 역할은 다음과 같습니다.

• plan, research, draft의 ticker, 기간, 출처 정합성을 확인합니다.
• draft의 핵심 주장과 research 근거가 일치하는지 봅니다.
• yfinance 가격 데이터와 차트 조건이 맞는지 확인합니다.
• plan_source, research_source frontmatter가 있는지 확인합니다.

lecture-designer

lecture-designer는 교육 설계 담당 에이전트입니다. 주요 역할은 다음과 같습니다.

• draft가 plan의 리포트 목표와 대상 독자를 따르는지 확인합니다.
• 초보자가 읽을 수 있는 흐름인지 봅니다.
• 문단이 과도하게 길지 않은지, 섹션 전환이 자연스러운지 검토합니다.
• price-chart가 리포트 흐름과 연결되는지 확인합니다.

content-editor

content-editor는 문장과 톤 담당 에이전트입니다. 주요 역할은 다음과 같습니다.

• plan의 톤과 목적에 맞게 draft 문장을 검토합니다.
• 중복 표현과 장황한 문장을 줄입니다.
• 제목, 소제목, 마무리 문장의 품질을 봅니다.
• 투자 권유처럼 보이는 표현을 제거합니다.

Codex Independent Review

코덱스의 리뷰는 같은 내용을 코덱스라는 다른 LLM 세션에서 다시 보는 교차 리뷰어입니다. 이 리뷰는 메인 세션의 추론으로 대체할 수 없습니다. 다음과 같은 검토 범위를 기반으로 최종 상태 pass, needs_fix, blocked 중 하나로 판단합니다.

• plan 누락
• 논리 비약
• 사실 오류 가능성
• 세 리뷰어가 놓칠 수 있는 blind spot

리뷰 에이전트는 몇 개가 적정할까요?

리뷰어를 늘릴수록 결과물의 품질이 단조롭게 좋아질 것 같지만, 실제 연구 결과는 그렇지 않습니다. 학계는 일관되게 ‘3~5명이 sweet spot, 6~8명이 상한’이라는 결론으로 수렴하고 있습니다.

4. 리뷰-수정 루프

리뷰가 끝나면reviews/<slug>.md의 status에 따라 다음 행동이 자동으로 분기됩니다.

• pass: Build 단계로 진행합니다(책임: Builder).
• needs_fix: 회귀 라우팅 표에 따라 이전 단계로 되돌아갑니다(책임: 해당 단계 Generator).
• blocked: 루프를 중단하고 인간 개입을 요청합니다(책임: 운영자).

needs_fix는 자동 처리, blocked는 항상 인간 호출입니다. 이 둘을 구분하지 않으면 에이전트가 해결할 수 없는 문제까지 무한 재시도하게 됩니다.

어디로 돌아갈지 정하기

리뷰에서 지적이 나오면 그 종류에 따라 돌아가야 할 단계가 달라집니다. 출처가 잘못된 글을 문장만 다듬어 내보내면 안 됩니다. 어떤 리뷰어가 어떤 종류의 지적을 했는지에 따라 어디부터 다시 손볼지를 미리 정해둡니다.

(예)

• fact-checker가 “출처나 근거가 빠졌다”고 하면 → research로 돌아가 자료부터 다시 봅니다.
• lecture-designer가 “구성이 어색하다, 차트 라벨이 이상하다”고 하면 → draft로 돌아가 원고를 손봅니다.
• content-editor가 “문장이 매끄럽지 않다, 같은 말이 반복된다”고 하면 → draft로 돌아가 표현을 다듬습니다.
• codex-independent가 “놓친 부분이 있다, 논리가 비약된다”고 하면 → 그 문제가 비롯된 단계로 돌아갑니다.

Generator의 세 가지 응답: acknowledge/defer/reject

회귀를 받은 Generator는 모든 리뷰 의견을 무조건 반영하지 않습니다. 세 가지 응답 중 하나를 선택하고 그 근거를 reviews/<slug>.md에 기록합니다.

• acknowledge : 지적을 수용하고 수정합니다.
• defer : 이번 라운드에서는 다루지 않고 다음 이슈로 미룹니다. plan/<slug>.followups.md에 기록합니다.
• reject : 지적이 잘못되었거나 plan 의도와 어긋난다고 판단해서 거부합니다. 거부 사유를 명시합니다.

종료 조건

핑퐁은 반드시 끝이 있어야 합니다. 다음 세 조건 중 하나가 충족되면 루프를 중단합니다.

• 수렴 : status가 pass가 되어 Build로 넘어갑니다.
• 반복 한계 : 최대 3라운드까지만 허용합니다. 4라운드가 필요하면 blocked로 전환합니다.
• 동일 지적 반복 : 같은 카테고리의 지적이 연속 2라운드 같은 문구로 등장하면 blocked로 전환합니다. 같은 곳을 두 번 찔러도 안 고쳐지면 에이전트만으로는 해결되지 않는다는 신호이기 때문입니다.

메모리에 기록하기

핑퐁이 끝난 뒤에는 그 라운드에서 반복적으로 등장한 지적을 기록으로 남깁니다. 다만 이 기록을 단순히 텍스트 파일에 쌓아 두기만 하면 다음 라운드에서 또 같은 실수가 나오기 쉽습니다. 그래서 이 시스템에서는 회고 결과를 memory 파일에 정리해 두고, 다음 작업이 시작될 때 inject-memory-context.sh 훅이 해당 도메인과 관련된 메모리를 자동으로 컨텍스트에 주입합니다. 회고가 “한 번 쓰고 끝나는 글”이 아니라, 다음 작업에서 곧바로 활용되는 살아 있는 기억이 되는 구조입니다.

같은 종류의 지적이 여러 작업물에서 반복된다면 그것은 한 작업의 문제가 아니라, 하네스 자체가 그 실패를 막지 못하고 있다는 신호입니다. 이때는 memory에만 적어 두는 것으로는 부족합니다. 더 강한 가드레일, 즉 lint 규칙, 자동 테스트, 리뷰어 프롬프트, 새 스킬 같은 형태로 끌어올려야 합니다.

5. Builder

Builder는 plan, research, draft, review, selected-image를 모두 읽고 최종 HTML을 만듭니다. Builder의 책임은 다음과 같습니다.

• reviews/<slug>.md가 존재하고 status가 pass인지 확인합니다.
• 선택된 이미지 JSON이 있는지 확인합니다.
• draft의 price-chart 블록을 yfinance 1일봉 데이터로 렌더링합니다.
• x축 라벨은 YYYY-MM-DD 형식으로 출력합니다.
• 최종 HTML에는 선택된 hero 이미지 한 장만 포함합니다.
• HTML 본문에는 [S1], [S2] 같은 검증용 인라인 참조 표식을 노출하지 않습니다.
• 최신 뉴스 5건 요약 블록을 독자가 클릭 가능한 형태로 포함합니다.

6. 훅 기반 가드레일

훅을 통해 가드레일 패턴을 구현합니다. 클로드 코드가 명령을 실행하거나 파일을 수정하는 등 주요 작업을 수행하는 순간마다 훅이 먼저 개입하여 작업이 정해진 규칙과 절차를 벗어나지 않도록 통제합니다. 구체적으로는 위험한 명령을 차단하고, 정해진 작업 순서를 강제하고, 출력물이 규칙을 지켰는지 검증하며, 필요한 컨텍스트를 자동으로 주입하는 역할을 합니다. 여기에서의 하네스 예시는 다음 여덟 가지 훅을 사용합니다.

1) block-dangerous-bash.sh

rm -rf /, sudo, 원격 스크립트 파이프 실행, 강제 푸시 같은 위험 명령을 차단합니다.

2) protect-sensitive-files.sh

.env, .git, 깃허브 워크플로, 핵심 금융 스타일 가이드, 출력 스펙 같은 보호 경로의 수정을 막습니다.

3) forbid-financial-advice.sh

draft와 HTML에 투자 권유, 수익 보장, 사기성 표현이 들어가면 차단합니다.

4) enforce-plan.sh

research, drafts, output 변경 시 선행 산출물이 있는지 확인합니다. 다음 순서를 강제합니다.

5) enforce-citations.sh

draft의 [3]과 같은 출처와 연동되어 있는지 등을 확인합니다.

6) remind-review.sh

draft가 변경되었는데 별도 세션 기반 4-way 리뷰가 없다고 나타나면 이후의 종료를 막고 다시 리뷰를 실행합니다.

7) inject-memory-context.sh

사용자 요청 도메인에 맞는 memory topic을 자동 주입합니다.

8) enforce-memory.sh

memory 파일이 변경되었을 때 scripts/validate_memory.py로 형식을 검증합니다. 이 구조는 같은 실패를 반복하지 않도록 경험을 문서와 검증 도구로 남기는 장치입니다.

8. 최종 상태 정의

하나의 리포트 산출물이 “완료되었다”고 말하려면 다음 조건을 모두 만족해야 합니다.

• plan/<slug>.md가 있습니다.
• research/<slug>.md가 있고 plan을 참조합니다.
• 종목 관련 리서치라면 최신 뉴스 100건 원자료와 분석이 있습니다.
• drafts/<slug>.md가 있고 plan과 research를 참조합니다.
• draft와 HTML에 최신 뉴스 5건 요약이 있습니다.
• 최신 뉴스 제목은 클릭 가능한 링크입니다.
• hero 이미지 후보 3개와 선택 JSON이 있습니다.
• reviews/<slug>.md가 있고 status가 pass입니다.
• 리뷰는 separate-session-4way 방식으로 기록되어 있습니다.
• output/<slug>.html이 생성되어 있습니다.
• HTML에는 검증용 [S1] 표식이 노출되지 않습니다.
• 투자 권유나 수익 보장 표현이 없습니다.

주요 폴더 구조 및 코드 설명

그러면 실제로 stock-report-harness 폴더의 구조와 주요한 실제 코드를 살펴보겠습니다. stock-report-harness 폴더를 열어 보면 .claude 아래의 그림처럼 훅과 에이전트, 스킬 등이 정리되어 있습니다.

중요한 파일들 위주로 살펴봅시다.

9. 더 나아가야 할 길

이것만으로도 주식 분석 리포트를 만드는 자동 시스템을 구축했다고 할 수 있습니다. 그러나 여기에서 시스템적으로 더 개선해 나갈 부분들이 있습니다. 바로 이 부분이 개발자가 해야 할 일입니다.

1) 데이터 추출 개선

yfinance로 시세를 매번 끌어오는 방식은 빠르게 시작하기에는 편리하지만, 보고서를 한 번 만들 때마다 같은 API를 반복해서 두드리는 구조라 비용과 지연이 누적됩니다. 또한 다음 그림처럼 클로드 코드의 rate limit에 걸려서 데이터를 아예 가져오지 못하는 경우도 발생합니다.

2) 뉴스 품질 개선

뉴스도 같은 문제를 안고 있습니다. 보고서를 만들 때마다 즉석에서 뉴스를 긁어 오면 양은 많아도 광고성 · 중복성 기사로 채워지기 쉽습니다.

3) 리뷰 에이전트의 독립 컨텍스트와 병렬 실행

현재 이 시스템에서 리뷰 에이전트의 독립 컨텍스트는 부분적으로만 보장됩니다. 실제 독립적으로 실행될 수도 있고 아닐 수도 있습니다. 그저 아래처럼 “권장” 수준으로만 강제하고 있을 뿐입니다. 또한 이 리뷰 에이전트 부분은 병렬 실행이 아닙니다.

4) 토큰 최적화

리포트의 경우 본문 구조도 고정되어 있습니다. 지금은 LLM Evaluator를 통해 토큰을 쓰면서 검증하는 방식으로 동작합니다.

이렇게 하네스 시스템을 활용하면 AI 에이전트의 불확실성을 통제하여 장기 작업을 안정적으로 수행할 수 있습니다. 물론 실무 환경에 맞추어 데이터 수집 방식이나 토큰 최적화 등 개선해 나갈 과제들도 여전히 남아 있지만 이제 우리가 고민해야 할 것은 함수 한 줄이 아니라 에이전트가 일하는 시스템 설계가 될 것이라는 점은 분명해 보입니다.

• 이 글은 길벗에서 출간된 책 <클로드 코드 제대로 시작하기>에서 발췌·편집한 글입니다. 원문은 [여기]에서 볼 수 있습니다.

ⓒ요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.