ropimen/claude-skill-kpi-calculator

KPI 계산기

하나 이상의 CSV/TSV 파일과 짧은 지침을 검증된 KPI 세트로 변환합니다. 각 KPI는 값, 단위, 방정식, 의미 및 기준 레이블을 포함합니다. 고정된 필드 목록은 없습니다. KPI는 데이터와 지침이 설명하는 모든 것에 맞게 설계됩니다. 데이터와 함께 첨부된 논문, 보고서 또는 이전 결과는 해당 KPI를 기여하며, 출처와 함께 사용자 데이터에 적용됩니다.

<skill_dir>는 이 파일이 포함된 폴더를 의미합니다. 작업 폴더(아래 "출력 위치" 참조)에서 python <skill_dir>/scripts/<name>.py로 스크립트를 실행하고, 절대 경로로 데이터 파일을 전달합니다.

python이 발견되지 않거나(또는 Microsoft Store가 열리면) Windows에서는 py -3을, 그 외에서는 python3을 아래 모든 명령어에서 사용하십시오. 시작 시 python --version으로 한 번 확인하십시오.

엄격한 규칙

1. 모든 숫자는 파일에서 실행된 코드에서 비롯됩니다. 절대 추정하거나, 눈으로 반올림하거나, results.json에 없는 값을 산문으로 명시하지 마십시오.
2. 제외된 KPI는 절대 계산되지 않으며 단일 "귀하의 요청으로 제외됨" 줄을 제외하고 어디에도 나타나지 않습니다.
3. 모든 가정은 "내가 이해한 것"(패턴, 역할, 단위, 보간, 시간대, 일/월 순서, 사용된 기본값)에 명시됩니다.
4. 실행당 최대 하나의 질문, 그리고 잘못된 추측이 결과를 변경할 경우에만 가능합니다(references/role-mapping.md, "질문해야 할 때" 참조). 그렇지 않으면 채택된 판단을 명시하고 진행합니다.
5. 모든 KPI는 사양으로 kpi_specs.json에 있으며, 기본 요소로 구성됩니다. 각각 basis: established(해당 분야의 표준) 또는 derived(기본 원리로 구축됨)로 레이블이 지정됩니다.
6. 기간에 대한 비율은 비율의 평균이 아닌 합계의 비율입니다. KPI가 달리 정의되지 않는 한.
7. 불규칙한 시간은 실제 시간입니다. 행을 시간 단계로 계산하지 마십시오. 각 열의 보간과 함께 타임스탬프를 통합하고 평균을 내십시오.
8. 검증 실패는 한 번 재확인됩니다(구문 분석 노트 → 매핑 → 사양), 그런 다음 경고와 함께 보고되며 절대 숨겨지지 않습니다.
9. 필드 지식은 Markdown에만 있습니다. 절대 필드별 로직을 스크립트에 추가하지 마십시오.
10. 참조의 값은 인용문입니다. 논문 또는 이전 결과에 보고된 숫자는 사양의 reference.reported에만 들어갑니다. 이는 계산에 입력되지 않으며 사용자의 결과로 표시되지 않습니다.

출력 위치

1단계에서 이를 결정하고 request.json → output_dir에 기록하십시오.

상황	작업 폴더(모든 JSON 파일, 스크립트의 cwd)	전달 파일
사용자가 폴더 이름 지정("D:/reports/line3에 결과 저장")	해당 폴더(생성)	동일한 폴더
Claude 앱(claude.ai / 데스크톱 채팅, /mnt/user-data/outputs/ 존재)	현재 디렉토리	/mnt/user-data/outputs/로 복사: 다운로드 가능한 파일로 나타남
Claude Code, 폴더 이름 없음	현재 디렉토리의 kpi_output/	동일한 폴더

전달 파일은 report.md, kpi_results.csv, kpi_run.py이며, 생성 시 kpi_chart.png, kpi_adhoc.py 및 제공되는 필드 팩이 포함됩니다. 작업 파일(request.json, profile.json, mapping.json, kpi_specs.json, results.json)은 감사를 위해 작업 폴더에 남아 있으며 요청 시에만 공유됩니다.

전달 파일을 사용자에게 제공하여 어디서든 저장할 수 있도록 하십시오:

• Claude 앱: 다운로드 가능한 파일 외에도 완성된 보고서를 Markdown 문서 아티팩트로 표시하여 읽거나, 복사하거나, 자체적으로 다운로드할 수 있도록 하십시오.
• Claude Code: 각 전달 파일을 해당 경로에 대한 링크로 나열하십시오. 호스트가 사용자에게 파일을 보내는 도구를 제공하는 경우(예: 데스크톱 앱의 파일 카드), 이를 통해서도 전달 파일을 보내십시오.
• 사용자가 요청하지 않는 한 작업 폴더 및 전달 파일 위치 외부에 절대 쓰지 마십시오.

나중에 kpi_run.py를 다시 실행하려면 입력 파일과 함께 폴더에 넣으십시오.

스크립트 우선, 임시 코드는 대체 수단으로만

항상 아래 스크립트를 실행하십시오. 다음 경우에만 자체 pandas 코드를 작성하십시오:

• 스크립트가 profile.json, mapping.json 또는 사양을 수정하여 고칠 수 없는 오류로 종료되는 경우(예: 파일 profile_csv.py가 구문 분석할 수 없음), 또는
• KPI에 기본 요소나 표현식으로 처리할 수 없는 연산이 필요한 경우(check_spec.py가 unknown_op 보고)

그런 다음:

1. 코드를 작업 디렉토리의 kpi_adhoc.py에 넣고, profile.json의 구문 분석 설정(또는 scripts/lib/io.py load)으로 데이터를 로드하고 자체적으로 실행 가능하게 유지하십시오.
2. 각 임시 KPI를 run_specs.py가 파일을 작성한 후 schemas/results.schema.json의 모든 필드와 함께 results.json → kpis에 추가하고 "computed_by": "ad_hoc"을 설정하십시오. 엔진이 계산한 값을 절대 변경하지 마십시오.
3. 보고서는 해당 KPI에 †를 표시하고 kpi_adhoc.py를 가리킵니다.

임시 코드에서도 사용자 또는 데이터에서 파생된 문자열에 eval/exec을 절대 사용하지 마십시오.

워크플로우

8단계를 순서대로 실행하십시오. 해당 단계에 필요할 때만 참조 파일을 읽으십시오.

1단계 [Claude] 요청 구문 분석 → request.json

references/request-parsing.md를 읽으십시오. field, mode, focus, include, exclude, custom, params, max_kpis, output_dir을 추출하십시오.

• 참조(논문, 보고서, 표준, 이전 결과)가 프롬프트에 첨부되거나 명명된 경우: references/reference-documents.md를 읽고, 데이터 파일과 구별하고, 각각을 전체 내용으로 읽고 해당 KPI를 request.json → references(id, 이름, 정의, 방정식, 위치, 보고된 값)에 기록하십시오. 데이터 파일만 2단계로 이동합니다.
• Excel 입력: 각 시트를 자체 CSV로 먼저 변환(pandas.read_excel(sheet_name=None))하고, <book>__<sheet>.csv로 이름을 지정하십시오.
• 포함 및 제외된 KPI → 이는 실행의 하나의 질문입니다. 해당 KPI에 대해 답변을 받을 때까지 아무것도 계산하지 마십시오.

2단계 [스크립트] 로드 및 프로파일링 → profile.json

python <skill_dir>/scripts/profile_csv.py FILE [FILE ...] --out profile.json

모든 열의 유형, 단위 힌트 및 구문 분석 노트를 확인하십시오. 숫자여야 하는 열이 text로 나온 경우 샘플을 살펴보고 진행하기 전에 구문 분석을 수정하십시오.

3단계 [스크립트] 시간 및 수집 패턴 감지 → profile.json (시간 섹션)

python <skill_dir>/scripts/detect_time.py --profile profile.json [--tz <IANA tz>] --out profile.json

references/collection-patterns.md를 읽으십시오. 스크립트는 evidence와 다른 타당한 candidates, 그리고 entity_column(그룹화 열에서 타임스탬프가 반복될 때), frequency(D, B, h, MS와 같은 pandas 별칭), gaps, duplicates 및 tz를 포함하여 하나의 패턴을 제안합니다. 사용자의 설명을 사용하여 패턴과 엔터티를 확인하거나 재정의하십시오. ambiguous_dayfirst가 true인 경우 가정을 명시하고(또는 두 판독값이 KPI 값을 변경하고 보류 중인 다른 질문이 없는 경우 질문), 사용자가 순진한 로컬 타임스탬프의 시간대를 지정하는 경우 --tz를 전달하십시오.

4단계 [Claude] 열 역할 매핑 → mapping.json

references/role-mapping.md를 읽으십시오. 각 열에 역할, 물리량, 단위 및 보간을 할당하고, 엔터티, 쌍, 조인, 재구성, 리샘플링 및 매개변수를 기록하십시오. 모든 언어의 헤더는 의미로 읽힙니다. 원래 이름을 유지하십시오.

그런 다음 mapping.json → sensitivity를 작성하십시오: 합리적으로 다르게 진행될 수 있었던 각 판단 호출(보간, 모호한 상태 클래스, 일/월 순서, 계획된 가동 중단, 가정된 단위 또는 매개변수)에 대해 하나의 변형을 사용합니다. 엔진은 각 변형 아래에서 모든 KPI를 다시 실행하고 최소-최대 범위를 보고하여 사용자가 어떤 숫자가 어떤 가정에 의존하는지 볼 수 있도록 합니다. 규칙 및 패치 형식은 references/role-mapping.md, "민감도 변형"에 있습니다.

5단계 [Claude] KPI 설계 및 선택 → kpi_specs.json

references/kpi-discovery.md(방법) 및 references/kpi-spec.md(형식, 기본 요소, 문법)를 읽으십시오. references/fields/에 필드와 일치하는 팩이 있으면 읽으십시오. 이는 정보를 제공하지만 절대 제한하지 않습니다.

선택 순서: 필수(include) 및 custom 우선 → references의 KPI(source: reference 사양 및 reference 블록 포함, references/reference-documents.md 참조) → 절대 exclude 안 함 → focus와의 관련성 기준, 확립된 것 우선, 파생된 것 나중, 중복 없음 → Claude의 자체 선택을 max_kpis(기본값 12)로 제한하십시오. 필수, 사용자 지정 및 참조 KPI는 절대 삭제되지 않습니다. 데이터가 지원할 수 없는 참조 KPI는 사양을 얻지 못하며 "자동으로 계산되지 않음" 아래에 나열됩니다.

그런 다음 사양을 확인하십시오:

python <skill_dir>/scripts/check_spec.py --profile profile.json --mapping mapping.json --specs kpi_specs.json \
       --request request.json

종료 코드 0 = 정상입니다. 종료 코드 1 = stderr의 JSON 오류: 사양 또는 매핑을 수정하고 다시 실행하십시오. 알 수 없는 단위는 경고로 반환됩니다. 하나가 결과를 변경하면 실행의 질문이 될 수 있습니다.

6-7단계 [스크립트] 계산 및 검증 → results.json, kpi_run.py

python <skill_dir>/scripts/run_specs.py --profile profile.json --mapping mapping.json --specs kpi_specs.json \
       --request request.json --out results.json --script-out kpi_run.py

각 사양은 그룹(엔터티)별로 실행되고 overall 규칙에 의해 전체 값이 계산됩니다. 실패하는 사양 또는 그룹은 이유와 함께 not_computed가 됩니다. 실행은 계속됩니다. stdout 요약은 모든 validation: 경고를 나열합니다.

동일한 실행은 또한:

• 각 민감도 변형에 대해 모든 KPI를 한 번씩 다시 실행하고 각 KPI에 sensitivity: {low, high, variants}를 저장합니다.
• 각 KPI를 해당 참조가 보고하는 값과 비교하여 KPI 단위로 변환합니다(comparison: 차이, 상대적 차이, 방향별 개선/악화, 보고된 값이 민감도 범위 내에 있는지 여부).
• data_health를 기록합니다: 매핑된 각 숫자 열에 대해 누락된 비율, 가장 긴 상수 실행, 강력한 이상값 및 불가능한 값(음수 개수, 100% 초과, 절대 영도 이하), 그리고 정규 계열에 대한 시간 범위.

모든 KPI가 검증 경고를 전달하는 경우: 구문 분석 노트(2단계), 매핑(4단계) 및 사양(5단계)을 한 번 재확인하고, 변경한 가장 이른 단계부터 다시 실행한 다음, 여전히 실패하면 경고와 함께 보고하십시오.

실행 후, results.json은 not_computed 항목(항상 references 및 include의 KPI에 대해)에 enable 텍스트(KPI를 계산 가능하게 하는 데이터 또는 매개변수)를 추가하고, 위의 대체 수단에 따라 임시 KPI 레코드를 추가하기 위해서만 편집할 수 있습니다. kpi_run.py는 입력의 해시, 프로필, 매핑, 사양 및 스킬 코드를 포함합니다. 스킬 없이 results.json( results_rerun.json으로)을 재생산합니다.

8단계 [스크립트 + Claude] 보고 → report.md, kpi_results.csv, 선택적 차트

python <skill_dir>/scripts/report.py --results results.json --request request.json \
       --mapping mapping.json --profile profile.json \
       --out-md report.md --out-csv kpi_results.csv [--chart kpi_chart.png]

--chart는 초점이 시간에 따른 변화와 관련되고 시간 열이 존재하는 경우에만 전달합니다. per_period 값이 있는 최대 두 개의 KPI를 플롯합니다(해당 KPI에 per_period 범위를 지정). 스크립트는 제외된 KPI가 results.json에 있으면 실행을 거부합니다.

references/report-format.md를 읽은 다음, 스크립트가 stdout에 나열하는 자리 표시자를 report.md를 제자리에서 편집하여 바꾸십시오:

• {{FINDINGS}}: 초점에 답하는 2-5개의 문장으로, results.json의 단위가 포함된 KPI 값을 인용합니다. 새 숫자는 없습니다. 민감도 범위가 넓은 KPI 이름(및 이를 이동시키는 판단), 비교가 있을 때 참조와의 비교(계산된 차이와 평결, 비교 가능성 제한 사용) 및 주요 KPI가 사용하는 열의 데이터 상태 플래그를 명시하십시오.
• {{READING:<kpi_id>}}: KPI당 하나의 문장: 방향 및 알려진 경우 일반적인 범위와 관련하여 좋거나 나쁩니다.

보고서의 다른 모든 것(이름, 방정식, 의미, 숫자)은 results.json에서 비롯되며 다시 작성되지 않습니다. 채팅에서 완성된 report.md를 표시하고 "출력 위치"에 설명된 대로 파일을 전달하십시오.

출력 체크리스트

답변하기 전에 다음 모두를 확인하십시오:

• 채팅 보고서는 순서대로 8개 섹션으로 구성됨: 내가 이해한 것 · KPI 개요 · KPI 세부 사항 · 결과 · 계산되지 않음 · 귀하의 요청으로 제외됨 · 데이터 문제 · 재현.
• 모든 KPI는 값, 단위, 방향, 기준 레이블, 소스, LaTeX 방정식 및 일반 텍스트 방정식, 기호가 n과 함께 원래 열 이름에 매핑됨, 의미, 판단, 경고를 표시함.
• 모든 필수 KPI는 계산되거나 "계산되지 않음" 아래에 어떤 데이터 또는 매개변수가 활성화하는지와 함께 나열됨.
• 제외된 KPI는 단일 "제외됨" 줄을 제외하고 어디에도 나타나지 않음(CSV도 확인).
• 수집 패턴 및 모든 가정이 명시됨; 모든 판단 호출은 질문하거나 명시하고 민감도 변형으로 테스트됨.
• 데이터 상태 테이블이 표시됨; 주요 KPI 입력에 대한 플래그가 결과에서 언급됨.
• 참조에서 찾은 모든 KPI는 계산되거나(인용, 위치, 정의 및 적응 표시) "계산되지 않음" 아래에 어떤 데이터가 활성화하는지와 함께 나열됨; 보고된 값은 인용된 것으로 표시됨.
• kpi_results.csv (BOM이 있는 UTF-8) 및 kpi_run.py가 작성되었고, 모든 전달 파일이 "출력 위치"에 따라 사용자에게 전달됨(Claude 앱의 다운로드 + 보고서 아티팩트; Claude Code의 경로 및 파일 카드).
• 차트는 초점이 시간에 따른 변화에 관한 경우에만 존재함.
• references/fields/에 팩이 없는 필드: 이번 실행에 사용된 KPI로 구축된 필드 팩을 references/fields/_template.md를 따르는 별도의 Markdown 파일로 제공하여 사용자가 검토하고 추가할 수 있도록 함. 스킬 폴더에 쓰지 마십시오.

비목표

예측 또는 모델 구축은 없음(스킬은 주어진 예측을 평가함). 라이브 피드 또는 데이터베이스 없음. 투자, 의료 또는 엔지니어링 조언 없음: 메트릭과 그 의미를 보고함. 통화 변환 없음: 혼합 통화는 플래그 지정되고 통화별로 계산됨.

기본값 (묻지 않고 사용, 사용 시 명시)

설정	기본값
무위험 수익률	0
연간화 계수	평일만 일일 252, 달력 일일 365, 주간 52, 월간 12, 분기별 4, 시간별 8760
MASE 계절 기간	시간별 24, 일간 7, 주간 52, 월간 12, 분기별 4, 그 외 1
불규칙 임계값	간격 CV > 0.5
간격 임계값	3 × 중간 간격
시간 열 구문 분석률	≥ 95%
프로필 샘플링	> 1,000,000 행 → 200,000 행 샘플(시간 열은 항상 전체 읽음)
max_kpis	12(Claude의 자체 선택만 해당)
백분율 처리	히스토그램이 0에서 100 사이에 있음을 암시하는 열의 0-100 값은 퍼센트로 처리됨(해당 열에 % 단위 힌트가 없거나 열 이름에 "percent" 또는 "rate"가 포함되지 않은 경우에도). 다른 모든 값은 원래 단위로 처리됨.