simul/learning/README.md

learning/ — AI 협업 워크플로

simul 코드는 사람이 직접 작성 한다. 하지만 어디서 시작할지 / 어떻게 평가할지 / 가드레일이 작동하는지 는 AI 와 효율적으로 협업한다.

본 디렉토리는 AI 협업의 표준화 다. 매번 같은 컨텍스트를 다시 설명하지 않도록.

---

워크플로 사이클

        ┌─────────────────────────────────────────┐
        ▼                                         │
  1. PROGRESS.md 보고 다음 단위 결정              │
        │                                         │
        ▼                                         │
  2. learning/M{N}.md 또는 todo-generator.md     │
       으로 todo 받기                             │
        │                                         │
        ▼                                         │
  3. 사람이 직접 코드 작성                        │
        │                                         │
        ▼                                         │
  4. learning/review-rubric.md 로 self-review    │
        │                                         │
        ▼                                         │
  5. (마일스톤 종료 시) canary-check.md 로       │
       4중 방어선 점검                            │
        │                                         │
        ▼                                         │
  6. PROGRESS.md 갱신 ────────────────────────────┘
       (마일스톤 표 + 카운터 + §6 다음 단위)

---

파일 인덱스

파일	용도	사용 시점
M0+.md	첫 마일스톤 6 단위 디테일 패키지 (즉시 사용 가능)	매 단위 시작 시
M{N}.md (예정)	M1 이후 마일스톤별 디테일 패키지	매 단위 시작 시
todo-generator.md	새 단위·마일스톤의 todo 트리 생성 AI prompt	M0+ 종료 후, 새 마일스톤 진입 시
review-rubric.md	구현 self-review AI prompt (5 axis rubric)	단위 PR 작성 직전 / 직후
canary-check.md	마일스톤 게이트 4중 방어선 점검 AI prompt	매 마일스톤 종료 시 (M2 / M3 / M5 …)

---

다음 마일스톤 컨텍스트 패키지는 어떻게 만드는가?

M1 부터는 학습자가 시점에 맞춰 직접 생성:

1. M0+ 종료 후 learning/todo-generator.md 의 prompt 를 새 Claude Code (또는 다른 AI) 세션에 붙여넣기
2. 입력: 마일스톤 = M1, 단위 = HarmonicAngleForce (또는 한 마일스톤 전체)
3. 출력 마크다운을 learning/M1.md 로 저장
4. 본인이 검토 후 정정 (특히 함정 / DoD / 추정시간)

한 번에 모든 마일스톤 패키지를 만들지 않는다. 진행하면서 해당 마일스톤이 다가올 때 만든다 — cone of uncertainty 가 좁혀진 후가 정확하다.

---

AI 와 작업할 때 권장사항

1. 컨텍스트 박기: prompt 본문 + ROADMAP.md + MIGRATION_CHEATSHEET.md + 해당 M{N}.md 를 같이 던진다. 분산 파일 없이 한 번에.
2. Definition of Done 강요: AI 가 "구현하면 끝" 이 아니라 DoD 체크리스트가 모두 통과 해야 끝.
3. NEVER 리스트 항상 인용: ROADMAP §10. AI 가 wgpu, Lepton, OpenMM XML 호환 같은 함정에 빠지지 않도록.
4. canary 가 살아있는지 확인: 매 마일스톤 종료 시 canary-check.md. 깨졌으면 그 마일스톤 안에서 fix, 다음 마일스톤 진입 금지.

---

비-AI 도구 (옵션)

• cargo test --workspace — 모든 Tier-1 테스트
• cargo test -p simul-lattice — canary
• cargo clippy --workspace --all-targets -- -D warnings — 린트
• tokei -e target -e .git -e .team-output — LOC 측정 (PROGRESS §2 갱신용)
• cargo doc --no-deps --open — 매 마일스톤 종료 시 trait API 시각 확인

이 명령어들의 출력을 review-rubric.md 또는 canary-check.md prompt 와 같이 AI 에게 던지면 자동 평가 가능.