zhnnky329/MathModeling-skills

MathModeling‑skills – 수학 모델링 대회를 위한 AI 보조 워크플로우 가드레일

개요

• 29개의 skills(재사용 가능한 소형 AI 구동 컴포넌트) 모음으로, 수학 모델링 대회 논문 작성을 위한 엄격하고 감사 가능한 파이프라인을 형성합니다.
• AI는 기계적인 작업(문제 파싱, 데이터 정리, 코드 생성, 재현성 확인, 수치 고정, 도표 생성)만 담당합니다. 모든 과학적 판단(모델 선택, 결과 해석, 서술)은 인간 팀의 몫입니다.
• 이 저장소는 Claude Code 및 Codex/ChatGPT의 네이티브 플러그인으로 제공되므로 채팅 세션에서 직접 스킬을 호출할 수 있습니다.

존재 이유

• 대회 팀은 문제 오독, 스크립트에서 생성되지 않은 수치 사용, 버그 수정 후 논문 업데이트 누락 등 워크플로우 실수로 인해 점수를 잃는 경우가 많습니다.
• MathModeling‑skills는 하드 게이트(G1‑G6)를 삽입하여 필수 확인 사항이 통과될 때까지 후속 단계를 차단함으로써 이러한 실수를 방지합니다.

작동 방식(파이프라인)

게이트	내용	의사결정 주체
G1 – PROBLEM_FRAMED	problem‑parser, problem‑classifier, related‑paper‑analyzer가 구조화된 문제 기술 생성.	AI (기계적)
G2 – METHOD_SCREENED	method‑selector가 주요 후보, 베이스라인, 선택적 대안 구축. 위험 탐지 요약이 가정, 데이터 커버리지, 출력 퇴화, 섭동 민감도, 스케일 확인.	인간 (채택할 후보 선택)
G2.5 – CHOSEN_BY_HUMAN	사용자가 선택한 방법과 근거 기록.	인간
G3 – CODE_AND_EXPERIMENT_REVIEWED	코드 생성기(python‑model‑code‑generator, matlab‑model‑code‑generator)가 스크립트 생성. code‑reviewer가 5가지 의미론적 검사가 포함된 JSON 리뷰 작성.	AI가 리뷰 작성, 인간이 승인
G4 – RESULTS_FROZEN	result‑report‑generator, robustness‑checker, math‑figure‑generator가 실험 보고서와 도표 생성. 모든 수치가 frozen_numbers.json에 기록됨. 이후 변경 시 로그 기록 및 재고정 필요.	인간이 고정 트리거, AI가 규칙 강제
G5 – PAPER_SECTION_READY	paper‑section‑writer가 고정된 스냅샷에서 섹션 초안 작성. paper‑polisher가 언어 정제. reference‑manager가 검증된 참고문헌 구축.	인간이 초안 작성, AI가 보조
G6 – AUDIT_LAYER_PASSED	3개의 독립적 감사(일관성, 완전성, 품질 보증)가 모두 통과되어야 submission‑packager가 최종 아카이브 생성.	인간이 실패 해결 필요

주요 컴포넌트

• workflow‑orchestrator – 각 하위 문제가 어느 게이트에 있는지 추적하고 '하위 단계 진부화' 규칙을 강제하는 중앙 상태 머신.
• symbol‑table‑builder – 모든 스크립트와 논문이 참조하는 단일 공유 용어집(symbol_table.md).
• data‑auditor‑cleaner – 읽기 전용 원본 데이터 폴더와 정리된 복사본을 생성하여 원본 데이터가 덮어쓰이지 않도록 보장.
• model‑code‑generator – 재현성을 위한 결정론적 코드(SEED = 2026). Python 및 MATLAB(대회 호환 기능으로 제한) 지원.
• math‑figure‑generator – 논문에 포함되기 전 시각적 render‑check를 통과하는 SVG/PNG 도표 생성.
• frozen_numbers.json – 원고에 나타나는 모든 수치의 유일한 진실 공급원. 수동 편집 금지.
• audit layer – 3개의 JSON 기반 감사. 모두 성공해야 하며, 파일 간 일관성, 리뷰 결과물의 존재, 워크플로우 준수 여부 검증.

설치 및 사용법

1. 저장소를 클론하고 ./install.sh 실행. 이 스크립트는 사용자, 프로젝트 또는 로컬 범위에서 mathmodeling‑skills 플러그인을 Claude/Codex에 등록합니다.
2. 새 채팅 세션에서 저장소의 Initial Prompt를 전송하여 워크플로우를 부트스트랩합니다.
3. 자연어 명령을 사용하여 오케스트레이터와 상호작용합니다. 예:
   • Q2 has experiment report round1 done. Let workflow‑orchestrator decide whether to iterate or lock the method.
   • Use robustness‑checker for Q1. Do not rerun the main model.
   • Run consistency‑auditor, then completeness‑auditor, then quality‑assurance‑auditor.
4. AI는 프로젝트 트리에 직접 저장되는 JSON 파일(리뷰, 감사, 고정된 수치)을 반환합니다. 인간이 이를 검토하고 다음 게이트로 진행합니다.

대상 아님

• 원클릭 논문 생성 도구가 아닙니다.
• 데이터, 결과, 인용을 조작하는 시스템이 아닙니다.
• 참가자의 과학적 판단을 대체하지 않습니다.
• 모든 대회에 대한 만능 해결책이 아닙니다. AI 사용이 특정 대회 규칙을 준수하는지 확인해야 합니다.

권장 사용자

• COMAP의 MCM/ICM, CUMCM 또는 AI 보조가 허용되는 유사한 대학 수준 모델링 대회 참가 팀.
• 규율 있고 재현 가능한 모델링 파이프라인을 교육하려는 교육자.
• 협업 데이터 분석 프로젝트에서 재현성과 감사 가능성을 강제하기 위한 템플릿을 찾는 연구자.

라이선스

• MIT – 자유롭게 사용, 수정 및 재배포 가능.

---

위의 모든 세부 정보는 저장소의 README에서 직접 가져온 것이며, 추가 기능은 추론되지 않았습니다.