파일 저장 프로토콜 (주식/ETF 분석용)

Overview

이 스킬은 주식/ETF 분석 에이전트가 결과를 파일로 저장할 때 따라야 하는 규칙을 정의합니다.

핵심 목표: 분석 결과의 영속성 보장 및 환각 방지

1. 파일 저장 필수 규칙 (CRITICAL)

환각 방지의 핵심: 분석 결과를 반드시 파일로 저장해야 합니다. 프롬프트로만 반환하면 데이터 손실 및 환각 발생 위험이 있습니다.

왜 파일 저장이 필수인가?

문제 설명

컨텍스트 손실 긴 대화에서 이전 분석 결과가 잘릴 수 있음

재현 불가 파일 없이는 분석 결과를 재검증할 수 없음

환각 위험 저장 없이 "저장됨"이라고 응답하면 환각

워크플로우 중단 다음 에이전트가 입력 파일을 찾지 못함

필수 사항 (MUST)

• 모든 분석 결과는 Write 도구로 파일 저장

• 저장 경로는 coordinator가 제공하는 output_path 사용

• 저장 성공 여부 확인 후 응답

• 저장 실패 시 명시적 FAIL 응답

금지 사항 (NEVER)

• 파일 저장 없이 분석 결과 "완료" 응답

• 저장 실패를 무시하고 진행

• output_path 무시하고 임의 경로 사용

1.5 Markdown 저장 규칙 (MANDATORY)

JSON 저장은 항상 필수이며, 사람이 읽기 위한 Markdown 요약도 반드시 저장합니다.

필수 규칙

• JSON과 MD 모두 저장 (둘 중 하나라도 누락 시 FAIL)

• MD는 JSON 내용을 요약/정리만 수행 (새 수치/새 출처 추가 금지)

• 파일명은 번호 접두어 고정:

• {output_path}/{NN}-{base}.md (base = JSON 파일명에서 .json 제거)

2. 저장 프로세스

Step-by-Step

Step 1: 분석 완료 후 JSON 객체 생성

Step 2: Write 도구로 파일 저장 Write( file_path="{output_path}/{filename}.json", content=JSON.stringify(analysis_result, null, 2) )

Step 3: 저장 성공 확인 └─ 성공: 정상 응답 반환 └─ 실패: FAIL 응답 반환 (환각 데이터 생성 금지)

저장 경로 컨벤션

coordinator(stock-consultant)가 제공하는 output_path 를 사용합니다:

consultations/{session_folder}/{filename}

예시: consultations/2026-01-14-TSLA-abc123/ ├── index-data.json # index-fetcher 출력 ├── rate-analysis.json # rate-analyst 출력 ├── sector-analysis.json # sector-analyst 출력 ├── risk-analysis.json # risk-analyst 출력 ├── leadership-analysis.json # leadership-analyst 출력 ├── material-summary.md # material-organizer 출력 (옵셔널) ├── macro-outlook.json # macro-synthesizer 출력 ├── 00-macro-outlook.md # macro-synthesizer 출력 ├── 00-materials-summary.md # 자료 정리 (materials_path 제공 시) ├── 01-stock-screening.json # stock-screener 출력 ├── 02-valuation-report.json # stock-valuation 출력 ├── 03-bear-case.json # bear-case-critic 출력 ├── 04-final-verification.json # stock-critic 출력 └── 05-consultation-summary.md # 최종 상담 보고서

에이전트별 출력 파일

에이전트 출력 파일 필수

stock-screener 01-stock-screening.json

O (포트폴리오 요청 시)

stock-valuation 02-valuation-report.json

O

bear-case-critic 03-bear-case.json

O

stock-critic 04-final-verification.json

O

거시경제 분석 출력 파일 (macro-analysis 재사용)

에이전트 출력 파일 필수

index-fetcher index-data.json

O

rate-analyst rate-analysis.json

O

sector-analyst sector-analysis.json

O

risk-analyst risk-analysis.json

O

leadership-analyst leadership-analysis.json

O

material-organizer material-summary.md

X (옵셔널)

macro-synthesizer macro-outlook.json , 00-macro-outlook.md

O

3. 저장 실패 시 응답

저장이 실패하면 절대 "저장됨"으로 응답하지 않습니다:

{ "status": "FAIL", "error": "FILE_SAVE_FAILED", "detail": "{filename} 저장 실패", "attempted_path": "{output_path}/{filename}", "action": "재시도 필요" }

실패 유형별 대응

실패 유형 코드 대응

경로 없음 PATH_NOT_FOUND

coordinator에 경로 확인 요청

권한 오류 PERMISSION_DENIED

경로 권한 확인

디스크 공간 DISK_FULL

공간 확보 후 재시도

알 수 없음 UNKNOWN_ERROR

에러 메시지 포함하여 보고

4. Write 도구 사용법

기본 사용법

Write( file_path="consultations/{session_folder}/02-valuation-report.json", content="{"status": "PASS", "ticker": "005930", ...}" )

JSON 포맷팅

들여쓰기 2칸으로 포맷팅

JSON.stringify(analysis_result, null, 2)

파일 확장자 규칙

데이터 유형 확장자

구조화된 분석 데이터 .json

마크다운 보고서 .md

원시 텍스트 .txt

5. 저장 확인 체크리스트 (MANDATORY)

저장 전 확인

• output_path 가 coordinator로부터 전달되었는가?

• 저장할 데이터가 완전한가 (모든 필수 필드 포함)?

• JSON 형식이 올바른가?

저장 후 확인

• Write 도구가 에러 없이 완료되었는가?

• 저장 경로를 응답에 포함했는가?

• 저장 실패 시 FAIL 응답을 반환했는가?

절대 금지

• 파일 저장 실패 시 "저장된 것처럼" 응답하지 않았는가?

• 저장 없이 분석 "완료"로 응답하지 않았는가?

6. 응답 템플릿

성공 시 응답

{ "status": "PASS", "output_file": "{output_path}/{filename}.json", "summary": { // 분석 결과 요약 } }

실패 시 응답

{ "status": "FAIL", "error": "FILE_SAVE_FAILED", "detail": "02-valuation-report.json 저장 실패", "attempted_path": "consultations/2026-01-14-TSLA-abc123/02-valuation-report.json", "action": "재시도 필요" }

메타 정보

version: "1.0" created: "2026-01-20" purpose: "파일 저장 프로토콜 통합 - 코드 중복 제거" based_on: "investments-portfolio/skills/file-save-protocol" consumers:

• stock-screener
• stock-valuation
• bear-case-critic
• stock-critic extracted_from:
• "파일 저장 필수 섹션 (investments-portfolio)"
• "저장 프로세스 섹션"
• "저장 실패 시 응답 형식" dependencies:
• Write output_path_pattern: "consultations/{YYYY-MM-DD}-{ticker}-{session_id}/"