Skip to content

hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-excel

hyper-excel

Verified

Use this skill when the user asks to read, analyze, create, or modify Excel workbooks (.xlsx, .xlsm) or turn CSV data into spreadsheets - inspecting sheets and formulas, editing cells while keeping existing formatting and formulas intact, building formatted reports with charts, or auditing formulas for broken ranges and error values. Do not use for plain dataframes, PDF or slide output, or VBA macro authoring.

references/large-data-and-pivots.ko.md

View on GitHub
# 대용량 데이터와 피벗

> 행 한도, 측정한 처리량, 그리고 "피벗 만들어줘"가 실제로 만드는 것.

## 하드 한도

| 한도 | 값 | 결과 |
|---|---|---|
| 시트당 행 | 1,048,576 | 120만 행 CSV는 시트 두 개나 실제 데이터베이스가 필요하다 |
| 시트당 열 | 16,384 | `XFD`에서 끝난다 |
| 셀 텍스트 길이 | 32,767자 | 더 길면 일부 작성기가 조용히 자른다 |
| 워크북당 서로 다른 셀 서식 | 65,490 | 행마다 서식을 주면 파일이 깨진다 |
| 시트 이름 | 31자 | 더 길면 거부된다 |
| 수식 내용 길이 | 8,192자 | 긴 배열 수식이 여기에 걸린다 |

행 한도가 문제다. 1,048,576행을 넘는 행을 조용히 버리는 변환은 실패보다 나쁘다. 그래서 `build_workbook.py`는 자르지 않고 거부하며, `profile`은 변환 전에 행 수를 보고한다.

## 측정한 처리량

조건: 이 기기(애플 실리콘), 2026-11-13, 120,000행 × 6열 CSV를 `.xlsx`로 변환한 뒤 `inspect`.

| 단계 | 결과 |
|---|---|
| CSV → `.xlsx`(`build --csv`) | 완료 |
| 결과 `inspect`(약 720,000셀) | 약 6초 |
| 피크 동작 | 패키지의 모든 파트를 메모리로 한 번 읽는다. 행은 그 바이트에서 스트리밍하므로 객체 그래프로 파싱하지 않는다 |

전체 구조 검사에 셀당 약 8µs이므로 100만 셀이면 CPU로 대략 10초, 파트당 수십 MB를 예상한다. 이 수치로 읽기 창을 계획한다. `inspect --rows N`은 전체 스캔을 줄이지 않고 시트별 표본만 줄인다.

## 스트리밍 규칙

- 시트를 하나씩 다룬다. `verify`는 대상 시트의 셀 딕셔너리를 만들므로 수백만 행짜리 시트에는 걸지 않는다.
- 시트를 로드해 다시 쓰지 말고 CSV 경로로 변환한다. CSV 경로는 파일을 한 번 메모리로 읽어 행 목록을 만든 뒤 시트 XML을 조립하므로 셀 단위 재작성보다 훨씬 싸다.
- 행마다 서식을 쓰지 않는다. 범위 서식 몇 개로 끝낸다.
- 수십만 행을 넘는 분석에 스프레드시트는 틀린 도구다. 그렇게 말하고 스크립트로 계산한 뒤 요약만 워크북에 쓴다.

## 피벗

**이 스킬은 네이티브 피벗 테이블을 만들지 않는다.** 피벗은 `pivotTableDefinition`과, 원본 행 사본을 담은 `pivotCacheDefinition`의 조합이다. 제대로 만들려면 캐시 필드 인덱스 매핑, 공유 항목 표, 행·열 필드 축이 필요하다. 손으로 쓰는 것이 불가능하지는 않지만 깨지기 쉽고, 캐시가 잘못되면 엑셀이 파일을 복구한다.

대신 할 일과, 그렇게 말할 것:

1. 집계를 계산해 헤더, 합계 행, 숫자 서식이 있는 일반 행으로 쓴다.
2. 사용자가 직접 피벗을 돌려야 하면 원본을 헤더 행과 자동 필터가 있는 일반 행으로 넣는다(빌드 스펙의 `"autofilter": "A1:D200"`). 그러면 엑셀의 삽입 → 피벗 테이블이 그 범위를 한 번에 받는다. `build`는 네이티브 `Table` 파트를 쓰지 않으므로 표를 넣었다고 말하지 않는다.
3. 사용자가 네이티브 피벗을 명시적으로 요구하고 이 기기에 엑셀이 있으면, 피벗은 엑셀에서 만들어야 한다고 말한다. 만들어 낸 척하지 않는다.

보고 문장은 이렇게 쓴다: `피벗은 계산된 일반 행으로 만들었습니다. 원본 범위에 필터를 걸어 두었으니 엑셀에서 그 범위로 피벗을 만들 수 있습니다.`

## 집계 계약

피벗 유사 요약을 계산할 때:

- 그룹 기준 키, 집계 함수, 필터를 밝힌다.
- 입력 행 수와 그룹 수를 보고한다.
- 키 기준, 또는 값 내림차순에 키 타이브레이크를 붙여 결정적으로 정렬한다. 그래야 출력이 재현된다.
- 맨 아래 합계 행을 두고, 상수가 아니라 수식(`=SUM(...)`)으로 만들어 수정에도 살아남게 한다.
- 숫자는 숫자로 유지한다. 숫자처럼 보이는 그룹 라벨(`2026`)은 키 열에서 텍스트다.

## 넓은 표

열이 300개인 표는 합법이고 쓸 수 없다. 만들기 전에 열 수를 보고하고 전치나 분할을 제안한다. 열 300개짜리 `.xlsx`는 받는 사람이 옆으로 끝없이 스크롤하게 만든다. 형식 문제가 아니라 전달 문제지만 한 번은 말한다.

## 메모리

패키지의 모든 파트를 열 때 메모리로 읽고, `verify`·`profile`은 다루는 시트의 파싱된 셀 목록을 더 둔다. 120,000행 시트는 편하다. 한 시트에 500,000행을 넘기면 수백 MB를 예상하고 `--rows`와 표적 읽기를 쓴다. 그 이상이 필요하면 워크북 작업이 아니라 데이터 처리 작업이다.

## Sources

> 확인 2026-11-13.

| 주장 | 출처 |
|---|---|
| 워크시트 한도: 1,048,576행, 16,384열, 셀당 32,767자 | <https://support.microsoft.com/en-us/office/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3> |
| 워크북당 서로 다른 셀 서식 65,490개 | <https://support.microsoft.com/en-us/office/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3> |
| 120,000행 변환과 약 6초 검사 | 2026-11-13 이 기기에서 `build_workbook.py`와 `inspect_workbook.py` 실행 |
| 행·열 초과를 자르지 않고 거부한다 | `build_workbook.py`의 `MAX_ROWS`/`MAX_COLS` 가드, 2026-11-13 self-test로 확인 |
| 피벗 테이블은 `pivotTableDefinition`과 원본 사본을 담은 `pivotCacheDefinition`이 필요하다 | <https://learn.microsoft.com/en-us/office/open-xml/spreadsheet/working-with-pivot-tables> |

### Evidence grade

측정한 처리량과 거부 동작은 `LOCAL`입니다. 한도와 피벗 구조 행은 마이크로소프트 문서입니다.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall