aging-clock

Aging Clock — Claude Code 플러그인

🎯 한눈에 보는 정체

DNA 메틸화 데이터로 "생물학적 나이"를 추정하는 Horvath 스타일 에피제네틱 시계를 만드는 Claude Code 플러그인입니다. 단순한 코드 레포가 아니라 **"노화 시계가 필요할 때 Claude가 자동으로 불러와 쓰는 전문가 매뉴얼 + 실행 가능한 Python 파이프라인"**입니다.

skills/aging-clock/SKILL.md 최상단의 frontmatter(name, description)를 통해, Claude가 사용자의 발화에서 "노화 시계", "Horvath clock", "GSE*" 같은 키워드를 감지하면 이 스킬을 자동 로드합니다.

---

🧬 무엇을 하는 도구인가 (비개발자 눈높이)

사람은 역연령(태어난 날짜 기준 나이)과 생물학적 나이(몸 상태 기준 나이)가 다를 수 있습니다.

• 40세인데 몸은 45세 → Age Acceleration +5
• 40세인데 몸은 35세 → Age Acceleration −5

DNA 메틸화(β값)라는 후성유전학 지표가 나이와 상관이 높다는 것이 2013년 Horvath의 발견이었고, 이 프로젝트는 그 기법을 Python으로 재현합니다.

---

📂 프로젝트 구조

aging-clock/
├── .claude-plugin/
│   └── plugin.json                    플러그인 매니페스트
├── skills/
│   └── aging-clock/                   스킬 본체 (이 디렉터리가 ~/.claude/skills/로 연결됨)
│       ├── SKILL.md                   스킬 정의·워크플로우
│       ├── scripts/                   실행 가능한 Python 파이프라인
│       ├── references/                데이터·규제·재현성 가이드
│       └── assets/                    한글 폰트 헬퍼 등
├── README.md                          이 파일
├── quickstart.md                      로컬 실행 가이드
└── LICENSE                            MIT License

파일 맵

파일	역할	핵심 요약
skills/aging-clock/SKILL.md	🧠 스킬 메타·워크플로우	STEP 0~8 단계별 안내
skills/aging-clock/scripts/setup_env.sh	🔧 환경 구축	--kr-mirror(카카오), --with-torch 옵션
skills/aging-clock/scripts/data.py	📥 데이터 수집·전처리	GEO 다운로드 + logit 변환
skills/aging-clock/scripts/model.py	🤖 ElasticNet 학습	ElasticNetCV, l1_ratio 7개 탐색
skills/aging-clock/scripts/mlp.py	🧠 PyTorch MLP(옵션)	HuberLoss + AdamW + Dropout 0.3
skills/aging-clock/scripts/evaluate.py	📊 평가·시각화	MAE, Pearson r, Age Acceleration
skills/aging-clock/scripts/run_pipeline.py	🚀 end-to-end CLI	한 번에 실행
skills/aging-clock/assets/korean-fonts.py	🇰🇷 한글 폰트 헬퍼	macOS/Win/Linux 자동 감지
skills/aging-clock/references/geo-datasets.md	📚 추천 데이터셋	GSE40279 등 + KoGES/K-CHIP
skills/aging-clock/references/reproducibility-checklist.md	✅ 재현성·MLOps	시드·누수 방지·MLflow
skills/aging-clock/references/kr-regulations.md	⚖️ 한국 법제	PIPA·IRB·SaMD·ISMS-P

---

📦 Claude Code에 설치하기

방법 1 — 마켓플레이스에서 설치 (✅ 권장)

Claude Code 세션 안에서:

/plugin marketplace add gaebalai/claudecode-company
/plugin install aging-clock@claudecode-company

이미 마켓플레이스를 추가한 경우 캐시만 갱신:

/plugin marketplace update claudecode-company
/plugin install aging-clock@claudecode-company

→ 일반 사용자에게 가장 간단한 경로입니다. 플러그인 매니페스트는 claudecode-company 마켓플레이스에서 관리됩니다.

방법 2 — 심볼릭 링크 (로컬 개발·기여자용)

# 저장소를 원하는 위치에 clone 후
git clone https://github.com/gaebalai/aging-clock.git ~/aging-clock
ln -sfn ~/aging-clock/skills/aging-clock ~/.claude/skills/aging-clock

→ Claude Code가 자동으로 스킬을 감지합니다. 원본에서 파일을 수정하면 즉시 반영되므로 개발·기여에 적합합니다.

방법 3 — 플러그인 개발 모드 (일회성 테스트)

claude --plugin-dir ~/aging-clock

→ 현재 세션에서만 플러그인으로 로드합니다. 디버깅에 유용.

📘 marketplace manifest 규격은 공식 문서 참고.

---

🔁 파이프라인 흐름

GEO accession (GSE*)              로컬 CSV
        │                            │
        └──────────┬─────────────────┘
                   ▼
        [전처리: 전치 → 결측보완 → 상수컬럼 제거 → [0.001,0.999] 클리핑 → logit]
                   ▼
        [ElasticNetCV 학습 (5-fold, n_alphas=50)]  또는 [PyTorch MLP]
                   ▼
        [평가: MAE 목표 3~5세, Pearson r ≥ 0.9]
                   ▼
        [산출물: clock_model.joblib / predictions.csv / pred_vs_true.png / meta.json]

---

🌟 이 프로젝트의 "차별점"

1. 한국 환경 로컬라이징

   • 카카오 pip 미러(skills/aging-clock/scripts/setup_env.sh)
   • AWS 서울 리전·NAVER Cloud 추천
   • macOS AppleGothic / Linux NanumGothic 한글 폰트 자동 설정

2. 규제 대응이 설계 단계에 박혀 있음

   • skills/aging-clock/scripts/run_pipeline.py에 면책 문구 상수화
   • PIPA(민감정보), 생명윤리법(IRB), SaMD, ISMS-P, 디지털의료제품법까지 망라

3. 실전 함정 방지

   • β값 VALUE 컬럼 fallback (skills/aging-clock/scripts/data.py)
   • Age Acceleration을 잔차 기반으로 계산해 역연령 바이어스 제거
   • train/test 누수 방지 체크리스트

4. 안전장치

   • 모든 리포트에 "의학적 진단 아님" 면책 문구 자동 삽입
   • MAE > 10년이면 데이터 품질 의심 가이드

---

🚀 빠른 시작 (CLI로 실제 학습 돌리기)

상세 가이드는 quickstart.md 참고.

# 스킬 디렉터리로 이동
cd skills/aging-clock