alchaincyf/huashu-excel

해결하는 문제

huashu-excel는 AI 기반 데이터 분석에서 발생하는 '침묵적 오류(silent errors)'라는 중요한 문제를 해결합니다. 일반적인 방법(예: pd.read_excel())은 병합 셀, 다단계 헤더, 또는 합계 행이 원시 데이터와 혼합된 구조적 이상을 감지하지 못해 수학적으로 잘못된 결과가 유효한 것처럼 보일 수 있습니다. 이 프로젝트는 원시 Excel 셀에서 최종 보고서에 이르기까지 데이터 무결성과 추적 가능성을 보장하는 엄격하고 감사 대응 가능한 워크플로우를 제공합니다.

작동 방식

이 프로젝트는 Claude Code, Cursor 등과 호환되는 에이전트 독립형 '스킬'로 동작하며, 엄격한 8단계 표준 운영 절차를 구현합니다:

1. 물리적 검사: openpyxl을 사용해 pandas로 로드하기 전에 원시 셀을 검사하여 구조적 '오염'(병합 셀, 헤더 등)을 식별합니다.
2. 정제: 추적 가능한 감사 히스토리를 가진 정돈된 형식으로 데이터를 변환합니다.
3. 일치화: 데이터를 이해한 후 사용자와 정의 및 기준을 명확히 합니다.
4. 분석: 통계적 함정(예: 심슨의 역설, 가짜 그룹화)을 탐지합니다.
5. 재정리: Excel 시트 자체의 '합계' 행을 체크섬으로 사용해 계산 결과를 검증합니다.
6. 배포: HTML, XLSX, 또는 DOCX 형식으로 보고서를 생성합니다.
7. 시각적 검증: 막대 그래프 축이 0에서 시작하는지 등 오해를 유도하는 요소가 없는지 확인합니다.
8. 품질 관리: 별도의 에이전트가 원시 데이터에서 독립적으로 결과를 재계산하여 검증합니다.

대상 사용자

정확성이 절대적으로 요구되는 프로페셔널 수준의 데이터 분석이 필요한 AI 에이전트 및 사용자를 위한 것입니다. 특히 인간이 수동으로 입력한 합계와 복잡한 포맷을 포함한 현실 세계의 비즈니스 스프레드시트를 다루는 사용자에게 적합합니다.

주요 특징

• 원시 셀 우선: pandas 처리 전에 openpyxl을 통해 원본 Excel 구조를 검사하여 정보 손실을 방지합니다.
• 체크섬 통합: 스프레드시트 내 존재하는 '합계' 행을 노이즈가 아닌 진실 검증 지점으로 간주합니다.
• 지각 정확성: 클리블랜드-맥길 지각 계층 기반의 차트 선택을 구현합니다(예: 3개 이상의 카테고리에 대해 원형 차트 거부).
• 강력한 통계: 편향된 비즈니스 데이터에 대응하기 위해 평균 대신 5수치 요약(Tukey의 저항성 통계)을 기본값으로 사용합니다.
• 최소 의존성: 핵심 검사 스크립트는 openpyxl 또는 표준 라이브러리만 필요하여 제한된 환경에서도 실행 가능합니다.