hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-excel
hyper-excel
VerifiedUse 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.
rules/failure-modes.ko.md
View on GitHub# 실패 유형
> 하나하나가 "끝난 것처럼 보이는데 틀린" 스프레드시트를 만든다. 각각에 도구가 보고하는 탐지가 있다.
## 1. 숫자가 텍스트로 저장됨
증상: 열에 `SUM`을 걸면 0이 나오거나 행을 건너뛴다. 엑셀에서 셀에 작은 초록 삼각형이 뜬다.
원인: CSV 가져오기, 웹 페이지에서 복사-붙여넣기, 앞에 붙은 아포스트로피 때문에 값이 문자열로 남는다.
탐지: `profile`이 숫자와 텍스트가 함께 있는 열에 `MIXED_TYPES`를, 앞자리 0이 사라질 값에 `LEADING_ZERO`를 보고한다. `verify_formulas`는 숫자·통화·백분율 서식 칸에 숫자 모양 문자열이 들어 있으면 `TEXT_NUMBER`를 올린다.
고침: 의도한 타입을 확인한 뒤 `--set-value`로 변환하거나, 빌드 시점에 숫자로 내보낸다. 수식을 `VALUE()`로 감싸 "고치는" 것은 금지다. 원본 데이터가 여전히 틀렸다.
## 2. 짧은 합계 범위
증상: 합계가 조금 모자란다. 표에는 모든 행이 들어 있다.
원인: 마지막 행을 붙이기 전에 수식을 썼거나, 필터로 행을 숨긴 뒤 보이는 부분에만 소계를 걸었다.
탐지: `verify_formulas`는 합계 범위가 이어진 데이터보다 먼저 끝나거나, 데이터 블록 안의 빈 행에서 멈추거나, 합계가 자신이 합하는 범위 안에 있으면 `RANGE_GAP`를 보고한다.
고침: 범위를 늘리거나 표 열을 참조한다. 새 합계를 독립 계산과 대조한다.
## 3. 낡은 캐시
증상: 다른 프로그램(pandas, `data_only=True` 스크립트)은 옛 숫자나 빈 값을 보여준다. 엑셀은 맞는 값을 보여준다.
원인: 수식을 `<v>` 없이 쓴 도구로 파일을 만들었거나, 데이터가 바뀌기 전에 캐시를 계산했다.
탐지: `inspect`가 `W_FORMULA_NO_CACHE`를 올리고 시트별 `formulaWithoutCache`를 보고한다. `verify`는 `totals.uncached`를 `mismatches`와 따로 센다.
고침: `recalc`로 값을 저장하거나, 캐시를 그대로 두고 어떤 리더가 빈 값을 볼지 알린다. 캐시와 재계산 개수는 따로 보고한다. 하나의 "불일치" 숫자로 합치지 않는다.
## 4. 퍼센트 100배 오류
증상: 성장률이 15%가 아니라 1,500%로 보인다.
원인: 값을 퍼센트 서식으로 `15`로 저장했거나, 일반 서식으로 `0.15`를 넣었다. 맞는 것은 `0.15`에 `0.0%`뿐이다.
탐지: `verify_formulas`는 퍼센트 서식의 상수 셀이 1보다 큰 값을 담으면 `PERCENT_AS_WHOLE`을(`15`는 잡고 `0.15`는 잡지 않는다), `profile`은 가져온 텍스트 안의 `%` 접미사에 `PERCENT_AS_TEXT`를 보고한다.
고침: 100으로 나눠 저장하고 퍼센트 서식을 적용한다. 숫자 값은 분수로 유지한다.
## 5. 날짜 로캘 반전
증상: `03/04/2026`이 한 도구에서는 3월 4일, 다른 도구에서는 4월 3일이 된다.
원인: 일-월 순서 로캘에서 입력·파싱했거나, 문자열로 저장했거나, 모호한 형식으로 변환했다.
탐지: `profile`은 일/월 순서 패턴(`01/31/2026`)이 있는 열에 `AMBIGUOUS_DATE`를, 그 밖에 텍스트로 저장된 날짜 모양 문자열(연-월-일 포함)에 `LOCALE_DATE_TEXT`를 보고한다.
고침: 날짜를 직렬 숫자로 저장하고 `yyyy-mm-dd` 서식을 명시한다. 날짜를 텍스트로 저장하지 않고, 일-월과 월-일 사이를 추측하지 않는다. 모호하면 모호하다고 보고한다.
## 6. 앞자리 0 소실
증상: 우편번호나 상품 코드 `00123`이 `123`이 된다.
원인: 가져오기나 변환에서 열을 숫자로 판정했다.
탐지: `profile`이 `LEADING_ZERO`를 개수와 열 이름으로 보고하고, 열 레코드에 `leadingZeros` 개수를 담는다. 그 열의 `kind`는 `number`가 아니라 `text`로 보고된다. 숫자라는 표기가 0을 잃는 변환을 부르기 때문이다.
고침: 빌드 스펙에서 그 열에 텍스트(`@`) 서식을 준다. 그러면 `build`가 값을 텍스트로 유지해 앞자리 0이 살아남는다. `build --csv`는 이 일을 스스로 한다. 필드가 `0`으로 시작하는 숫자열이면 그 열 전체에 `@` 서식을 주므로 `007`이 숫자로 다시 바뀌지 않는다. 코드가 명시적 숫자 서식 아래에 있으면 `build`가 그 셀들을 담아 `W_LEADING_ZERO_LOST`를 보고한다. 변환을 강제하는 것이 값이 아니라 서식이기 때문이다. 이미 있는 파일은 `patch`로 그 셀을 `--as-text`로 고친다. 숫자로 다시 해석되면 조용한 데이터 손실이므로 빌드 결과를 다시 읽어 0을 확인한다.
## 7. 자기 참조와 순환
증상: 엑셀이 순환 참조 경고를 띄운다. 값은 0이거나 마지막에 입력한 값이다.
원인: 합계를 자기 범위 안에 두었거나 수식 사슬이 순환한다.
탐지: `verify_formulas`는 직접 걸리면 `SELF_REFERENCE`를, 더 긴 고리는 순환으로 보고하고 고리의 모든 셀을 밝힌다.
고침: 합계를 범위 밖으로 옮기거나 고리를 끊는다. 반복 계산을 켜서 덮지 않는다.
## 8. 가져온 텍스트의 수식 주입
증상: 누군가 파일을 열기 전까지는 없다. `=`, `+`, `-`, `@`로 시작하는 값이 수식이나 DDE 호출로 실행된다.
원인: 가져온 CSV 텍스트를 작성기가 선행 `=`를 이스케이프하지 않고 수식으로 썼다.
탐지: 빌더가 선행 `=`, `+`, `-`, `@`가 붙은 값을 텍스트 셀로 쓰고, 빌드 출력의 `I_NEUTRALIZED`에 개수와 셀 목록을 담아 보고한다. 그 보고를 검토한다.
고침: 텍스트(문자열 타입)로 저장하고, 어느 열에서 몇 개를 중화했는지 보고한다. 값을 조용히 지우지 않는다. 사용자가 봐야 할 값일 수 있다.
## 9. 수식이 많은 파일에 캐시 없음
증상: 계산하지 않는 리더로 받은 사람이 빈 보고서를 본다.
원인: 수식을 캐시 없이 썼고 재계산하지 않았다.
탐지: `inspect`가 `W_FORMULA_NO_CACHE`를 시트별 `formulaWithoutCache` 개수와 함께 올린다. `verify`는 값이 없는 수식이 하나라도 있으면 `cache_complete`를 `partial`로 보고한다.
고침: `recalc`. 값을 쓰고 `fullCalcOnLoad`를 설정하므로 엑셀은 열 때 원본부터 다시 계산한다.
## 10. 대상 엑셀이 모르는 최신 함수
증상: 구버전 엑셀에서 `#NAME?`. `XLOOKUP`, `XMATCH`, `FILTER`, `SORT`, `UNIQUE`, `SEQUENCE`, `LET`, `LAMBDA`로 쓴 파일이다.
탐지: `verify_formulas`가 함수와 셀을 담아 `NEWER_FUNCTION`을 보고한다. 엑셀이 이런 함수를 저장할 때 붙이는 `_xlfn.`/`_xlws.` 접두사를 걷어내고 판정하므로 엑셀이 쓴 파일도 잡힌다.
고침: 동등한 식으로 바꾸거나, 파일이 요구하는 최소 엑셀 버전을 밝힌다.
## 11. 큰 시트의 휘발성 수식
증상: 파일을 여는 데 오래 걸리고, 키를 누를 때마다 전부 다시 계산한다.
탐지: `verify_formulas`가 셀마다 함수마다 `VOLATILE_FUNCTION`을 한 건씩 올리고 각 건에 셀을 적는다. 보고에 함수별 개수가 필요하면 그 건수를 세어 쓴다.
고침: `OFFSET`/`INDIRECT`/`TODAY`/`NOW`/`RAND`를 정적 참조나 보조 열로 바꾸거나, 왜 필요한지 밝힌다.
## 12. 들쭉날쭉한 행과 한 열의 혼합 타입
증상: 합계는 되는데 필터나 피벗에서 행이 조용히 빠진다.
원인: 한 열에 숫자와 텍스트가 섞였거나, 데이터 블록 안에 빈 행이 있다.
탐지: `profile`이 열별 `kind`를, 혼합 열에 `MIXED_TYPES`를 보고하고 열 레코드가 빈 칸을 센다.
고침: 빌드 전에 정규화하고, 빠지거나 강제 변환된 행을 보고한다.
## 13. 수식 하나가 검증 보고 전체를 지운다
증상: `verify`가 파싱 오류로 끝나고 셀을 하나도 알려주지 않는다. 어느 수식이 틀렸는지, 나머지가 괜찮은지 알 수 없다.
원인: 셀 하나가 수식 오류가 아니라 파이썬 예외를 냈다. 범위를 벗어난 `DATE(2026,13,1)`, 인덱스가 없는 `CHOOSE()`, `10^400`, `POWER(-8,1/3)`이 그렇다.
탐지: 고친 뒤에는 따로 필요 없다. 그 셀이 수식과 예외 종류를 담은 채 `unevaluated`에 남고, 나머지 수식은 그대로 평가·비교된다. 문제는 `unevaluated` 목록 없이 `E_PARSE`만 찍히는 실행이다.
고침: 워크북은 건드리지 않는다. `unevaluated`를 먼저 읽는다. 거기 있는 셀은 맞는 것이 아니라 검증되지 않은 것이다. 수식이 실제로 정상 범위인 셀만 `recalc`로 값을 받는다.
## 14. 아무 데도 가리키지 않는 차트 계열
증상: 차트는 만들어지고 파일도 열리는데 그림이 비어 있다.
원인: 계열 참조에 시트가 두 번 붙었다. 스펙이 `Data!A2:A3`라고 했는데 `Chart!Data!A2:A3`가 되면 엑셀은 잘못된 참조로 본다. 같은 증상이 drawing 관계가 엉뚱한 시트에 붙어도 나온다. 차트 파트는 있는데 그 파트를 가리키는 시트가 없는 경우다.
탐지: `inspect`가 시트별 차트 파트와 종류를 보고하므로 차트가 다른 시트 밑에 붙은 것이 보이고, `xl/charts/chart1.xml`을 읽으면 `<c:f>` 참조가 그대로 나온다.
고침: `categories`/`values`에는 시트를 붙이지 않은 범위(차트가 놓인 시트로 한 번만 한정됨)나 시트를 모두 붙인 범위 중 하나만 준다. 차트 파트를 다시 읽어 각 참조에 `!`가 정확히 하나인지 확인한다.
## Sources
> 확인 2026-11-13.
| 주장 | 출처 |
|---|---|
| 퍼센트 셀은 분수를 담아야 하고, 15를 저장하면 1,500%로 보인다 | <https://support.microsoft.com/en-us/office/format-numbers-as-percentages-9b46a1f1-1c2b-40a8-9a9f-d9d9e1b0e8a1> |
| 계산하지 않는 리더가 보는 값은 수식 셀의 `<v>` 캐시다 | <https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.cellvalue> |
| 가져온 텍스트의 선행 `=`, `+`, `-`, `@`는 수식 주입 경로다 | <https://owasp.org/www-community/attacks/CSV_Injection> |
| `XLOOKUP`, `LET`, `FILTER`, `TEXTJOIN`은 구버전 엑셀에 없다 | <https://support.microsoft.com/en-us/office/xlookup-function-b7fd680e-6d10-43e6-84f9-88eae8bf5929> |
| 순환 참조는 조용히 풀리지 않고 계산을 깨뜨린다 | <https://support.microsoft.com/en-us/office/remove-or-allow-a-circular-reference-in-excel-8540bd0f-6e97-4483-bcf7-1b49cd50d123> |
| 탐지 코드와 임계값은 이 스킬이 정한 것 | `verify_formulas.py`의 `static_findings`, 2026-11-13 확인 |
### Evidence grade
탐지 코드와 심각도는 `LOCAL`입니다. 엑셀·OWASP 행은 기반 동작에 대한 벤더·표준 문서입니다.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 469k | Updated | Claude CodeCodex | Verified | Install |
| 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: 469k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |