From 5f0d10bc68b2e42bbdc79ce28f16e3020838e5c3 Mon Sep 17 00:00:00 2001 From: kakyungkim Date: Mon, 27 Jul 2026 14:14:01 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20AI=20Scientist=20=EC=84=A4=EA=B3=84=20?= =?UTF-8?q?=EC=A0=95=EB=A6=AC=20+=20HTML=20=EC=8B=9C=EA=B0=81=ED=99=94=20?= =?UTF-8?q?=EC=9D=B4=EA=B4=80=20(ai=5Fscientist/)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit kkkim-pipeline에서 작성한 ai_scientist/ 문서 6편(README, 01-05)과 HTML 시각화(output_v01/, mermaid 6종)를 main으로 이관. - 레이어 A(단일 랩 자동화) + 레이어 B(멀티 AI 협업 인계) 설계 정리 - 원문 근거: docs/HARNESS.md, .claude/skills, guide/ 두 문서 kkkim-pipeline 브랜치에서는 별도 커밋으로 삭제. --- ai_scientist/01_overview.md | 37 ++ ai_scientist/02_single_lab_harness.md | 107 +++++ ai_scientist/03_multi_ai_collaboration.md | 118 +++++ ai_scientist/04_design_principles.md | 59 +++ ai_scientist/05_component_map.md | 51 +++ ai_scientist/README.md | 48 ++ ai_scientist/output_v01/README.md | 25 ++ ai_scientist/output_v01/index.html | 507 ++++++++++++++++++++++ 8 files changed, 952 insertions(+) create mode 100644 ai_scientist/01_overview.md create mode 100644 ai_scientist/02_single_lab_harness.md create mode 100644 ai_scientist/03_multi_ai_collaboration.md create mode 100644 ai_scientist/04_design_principles.md create mode 100644 ai_scientist/05_component_map.md create mode 100644 ai_scientist/README.md create mode 100644 ai_scientist/output_v01/README.md create mode 100644 ai_scientist/output_v01/index.html diff --git a/ai_scientist/01_overview.md b/ai_scientist/01_overview.md new file mode 100644 index 0000000..23c388a --- /dev/null +++ b/ai_scientist/01_overview.md @@ -0,0 +1,37 @@ +# 01. 개요 — AI Scientist가 무엇을 자동화하는가 + +## 출발점 + +이 프로젝트가 풀려는 연구 문제는 gene별 chromatin→transcription **lag**(activation/shutdown)을 정량하고, baseline epigenomic feature로 epigenetic drug response timing을 예측하는 것이다. 1차 데이터셋은 Human HSPC 10x Multiome(GSE209878)이다. 이 도메인 문제 자체는 `pipeline/hspc-velocity-benchmark/`가 담당한다. + +AI Scientist 설계의 목표는 이 연구 문제를 푸는 **과정 전체**를 자동화하는 데 있다. 사람이 도구를 하나씩 손으로 돌리는 대신, AI 멤버들이 연구의 각 단계를 나눠 맡아 이어서 돌아가게 한다. + +## 연구 과정을 어떤 단계로 나눴나 + +전통적인 연구 흐름을 AI가 맡을 수 있는 단계로 나누면 다음과 같다. 괄호 안은 이 저장소에서 그 단계를 맡는 주체다. + +1. **논문 탐색·정리**: 선행연구를 찾아 정리하고, 우리 기여를 정직하게 위치시킨다. (`literature-scout`, 그리고 별도 하네스로 돌려 `paper_analysis/`에 반입한 dual-lens 분석 14편) +2. **가설 설정·차별화**: 무엇이 새로운지, 어떤 실험이 가장 싸게 그것을 입증하는지 정한다. (`novelty-strategist`, `research-methodologist`) +3. **실험 설계·감사**: 가설을 검증 가능한 실험으로 바꾸고 누수·통계 위험을 미리 잡는다. (`research-methodologist`) +4. **실험 수행·분석**: 파이프라인을 돌려 eval·통계·cross-dataset 재현을 계산한다. (`hspc-velocity-analyst` + `scripts/` P0–P5) +5. **집필·그림**: 결과 파일에서 원고와 그림을 만든다. (`manuscript-writer` + `figures/figNN_*.py`) +6. **검수·리뷰**: 제출 전 적대적 자체검토와 정식 venue 리뷰를 돌린다. (`paper-critic`, `reviewer`) +7. **발표**: 청중에 맞춰 슬라이드와 발제를 만든다. (`presenter`) + +이 일곱 단계를 사람이 매번 순서대로 부르지 않도록, 자연어 요청을 멤버에 배정하는 라우팅표(`CLAUDE.md`)와 여러 단계를 엮어 실행하는 오케스트레이터 Skill(`paper-production-orchestrator`)을 두었다. 자세한 구조는 [02_single_lab_harness.md](02_single_lab_harness.md)에서 다룬다. + +## 왜 한 명의 AI로 끝내지 않았나 + +연구 팀은 한 사람이 아니다. 이 프로젝트도 데이터셋별로 담당자가 다르고(mouse brain, SHARE-seq, human brain, HSPC 등), 팀원마다 쓰는 AI도 Claude, Codex, Gemini로 갈린다. 한 AI가 논문 한 편을 끝까지 끌고 가는 구조(레이어 A)만으로는 이 협업을 담을 수 없다. + +그래서 두 번째 레이어를 설계했다. 팀원 A의 AI가 끝낸 작업을 팀원 B의 AI가 자동으로 이어받는 인계 체계다. 신호를 JIRA 상태 전환 하나로 일원화하고, 인계 맥락을 정형화된 Handoff 코멘트로 강제하며, 모든 AI가 같은 MCP 설정으로 JIRA·GitHub를 읽고 쓰게 한다. 자세한 구조는 [03_multi_ai_collaboration.md](03_multi_ai_collaboration.md)에서 다룬다. + +## 두 레이어가 공유하는 발상 + +레이어 A와 B는 다른 문제를 풀지만 같은 원리 위에 서 있다. + +- **다음 주체가 하나만 읽어도 착수할 수 있게 한다.** A에서는 결과 파일(`results/FINDINGS.md`), B에서는 JIRA Handoff 코멘트가 그 역할을 한다. +- **자동화하되 사람 게이트를 남긴다.** A에서는 공개·main 병합, B에서는 초기 도입기의 Slack 승인이 사람 손을 거친다. +- **폭주와 비용을 구조로 막는다.** A에서는 검증 게이트가 근거 없는 주장을, B에서는 Hop Count 상한과 큐가 무한 인계와 토큰 낭비를 막는다. + +이 공통 원리는 [04_design_principles.md](04_design_principles.md)에 모아 두었다. diff --git a/ai_scientist/02_single_lab_harness.md b/ai_scientist/02_single_lab_harness.md new file mode 100644 index 0000000..6bbbd35 --- /dev/null +++ b/ai_scientist/02_single_lab_harness.md @@ -0,0 +1,107 @@ +# 02. 레이어 A — 단일 랩 자동화 (한 AI가 논문 한 편을 끝까지) + +한 연구자의 연구 과정 전체를 여러 agent 멤버가 나눠 맡아 자동으로 돌리는 구조다. 이 하네스를 "하나의 연구 랩"으로 보는 지도가 `docs/HARNESS.md`이고, 라우팅과 산출물 계약 요약은 `CLAUDE.md`의 *Agent routing & artifact contract* 절에 있다. + +핵심 발상은 이렇다. agent는 직원이 아니라 랩의 **멤버(연구원)**이고, 사람과 메인 루프가 랩을 이끄는 **PI**다. PI는 무엇을 할지 정하고 승인·공개를 책임지되, 실제 작업은 멤버가 파일로 주고받으며 이어서 한다. + +## 1. 멤버 명부 + +`.claude/agents/`에 정의된 멤버는 다음과 같다. 하나(`hspc-velocity-analyst`)만 이 프로젝트 도메인 전용이고, 나머지는 다른 논문에도 재사용할 수 있게 만들었다. + +| 멤버 | 벤치 | 역할 | +| --- | --- | --- | +| `hspc-velocity-analyst` | 분석실 | 도메인 슬롯. HSPC velocity-lag 파이프라인(P0–P5)·eval·통계·cross-dataset 실행/확장, 결과 파일 유지 | +| `literature-scout` | 문헌·기획 | 선행연구 탐색, 정직한 포지셔닝, related work | +| `novelty-strategist` | 문헌·기획 | 차별화 각도와 가장 값싼 입증 실험 제안 | +| `research-methodologist` | 문헌·기획 | 가설·기여문·실험설계, 누수·통계 감사 | +| `manuscript-writer` | 집필실 | 프리프린트·저널·블로그 본문 초안과 그림 연계 | +| `presenter` | 집필실 | 청중 맞춤 슬라이드·발제 | +| `paper-critic` | 심사·QA | 제출 전 적대적 자체검토와 그림 시각 QA | +| `reviewer` | 심사·QA | 정식 venue 스타일 공식 리뷰(선택) | +| `paper-orchestrator` | 코디네이션 | 멀티 agent 작업의 **계획**만 수립(실행은 PI) | +| `design` | 엔지니어링 | 로고·아이콘·브랜드·그림 미감 | +| 그림 생성 스크립트 | 엔지니어링 | `figures/figNN_*.py`. 결과 파일에서 그림 생성·번호 정합 | + +그림 생성을 agent가 아니라 결정론적 스크립트로 둔 점이 설계상의 선택이다. `manuscript-writer`가 스크립트를 실행해 결과 파일로부터 그림을 만들고, 단순 재생성이면 메인 루프가 직접 돌린다. 숫자를 손으로 하드코딩하지 않고 결과 파일에서만 뽑게 해 재현성을 지킨다. + +## 2. 자연어 라우팅 — 누가 시작할지 사람이 매번 안 정한다 + +요청에 agent 이름이 없어도 `CLAUDE.md`의 라우팅표가 자연어 요청을 멤버에 배정한다. 예를 들면 이렇게 나뉜다. + +- "분석 돌려줘 / 재실행 / eval·통계 / cross-dataset 재현" → `hspc-velocity-analyst` +- "프리프린트·섹션 써줘 / 그림 만들어줘" → `manuscript-writer` +- "선행연구 / 스쿱 확인" → `literature-scout` +- "차별화 각도 / 뭘 새로 해야 하나" → `novelty-strategist` +- "가설·실험설계 점검·감사" → `research-methodologist` +- "제출 전 자체검토 / 그림 QA" → `paper-critic` +- "발표자료 / 슬라이드" → `presenter` + +여러 단계를 엮는 요청("분석→집필→그림→검수까지", "critic 지적 반영해")은 단일 멤버가 아니라 오케스트레이터 Skill로 보낸다. + +## 3. 오케스트레이터 — 여러 단계를 정해진 순서로 + +`paper-production-orchestrator` Skill(`.claude/skills/paper-production-orchestrator/SKILL.md`)이 논문 생산 루프의 입구다. 메인 루프(PI)가 이 Skill을 실행하며 멤버를 순서대로 부른다. subagent는 subagent를 못 부르므로, "계획만 짜는" `paper-orchestrator` agent와 달리 실제 실행은 이 Skill이 맡는다. + +실행 흐름은 다음과 같다. + +``` +0. 단일 컨텍스트 로드 — manuscript/PAPER_DIRECTION.md 를 먼저 읽는다 + (현재 thesis · claim 등급표 · loop 규율 · 진행상태. 멤버 호출 전 이 문서를 넘긴다) +1. 모드 분기 — 풀 파이프라인 / 부분 재실행 / 하류만 다시 +2. (선택) 기획·근거 — research-methodologist / literature-scout / novelty-strategist +2.5 claim-defensibility 게이트 — headline·novelty claim이 본문에 들어가기 전 필수 +3. 분석·eval — hspc-velocity-analyst → results/FINDINGS.md +4. 집필 + 그림 — manuscript-writer → draft_v2.md + draft_v2_ko.md, figures/*.png +5. 검수 — paper-critic (적대적 + 그림 시각 QA) +6. 수정 — manuscript-writer 가 지적 반영 +7. (선택) 정식 리뷰 — reviewer → REVIEW--.md +8. 검증 게이트 — 헤드라인 숫자 결정론적 재계산 (실패하면 멈추고 사람에게 보고) +9. (선택) 발표 — presenter +``` + +핵심은 **부분 재실행**이다. 이미 만들어진 산출물이 있으면 요청한 단계만 다시 돌리고 나머지는 기존 파일을 재사용한다. "그림만 다시"면 4단계만, "최신 결과로 본문 갱신"이면 변경 지점의 하류 단계만 돌린다. + +## 4. 산출물 계약 — 대화가 아니라 파일로 넘긴다 + +멤버는 중간 결과를 대화에만 남기지 않고 정해진 파일로 넘긴다. 다음 멤버는 그 파일을 읽고 이어서 일한다. + +| 단계 | Writer | 산출물 | 다음이 읽음 | +| --- | --- | --- | --- | +| 분석·eval | hspc-velocity-analyst | `results/FINDINGS.md` + `results/*.csv` + `results/*.md` | 집필·검수 | +| 집필·그림 | manuscript-writer | `manuscript/draft_v2.md` + `draft_v2_ko.md`(영/한 동시), `figures/*.png` | 검수·리뷰·발표 | +| 검수 | paper-critic / reviewer | `manuscript/REVIEW--.md` | 집필(수정) | +| 발표 | presenter | 슬라이드·발제 | 사람 | +| 상태 핸드오프 | 전원 | `HANDOFF.md`, `TODO.md`, `SESSION-LOG.md` | 다음 세션 | + +이 계약 덕분에 멤버가 교체되거나 세션이 끊겨도 작업이 이어진다. 다음 주체가 산출물 파일 하나만 읽으면 착수할 수 있다는 기준을 지킨다. + +## 5. 실험 실행 엔진 — 파이프라인 P0–P5 + +분석 단계의 실제 계산은 `pipeline/hspc-velocity-benchmark/scripts/`가 담당한다. `hspc-velocity-analyst`가 이 스크립트들을 돌려 결과 파일을 만든다. 내부 단계 표기는 P0부터 P5까지다. + +- **P0: 다운로드·provenance.** `download_data.sh`로 GSE209878를 받고 `download_manifest.tsv`(sha256)와 `P0_provenance.md`를 남긴다. +- **P1: 통일 전처리.** `p1_build.py`가 공통 branch를 만든다. 여기서 preprocessing 차이와 method 차이를 분리한다. +- **P2: velocity method 실행.** `p2_multivelo.py`, `p2_moflow.py`, `p2_crakvelo_*`, `p2_multivelovae.py` 등으로 여러 method를 같은 전처리 위에서 돌린다. +- **P3: 재현성 검증.** `p3_concordance.py`, `p3_crossdataset_concordance.py`, `p3_scrambled_null.py`로 method 간·dataset 간 일치도와 null을 계산한다. +- **P4: permutation FDR.** gene 단위 다중검정을 통제한다. +- **P5: bootstrap 안정성.** shuffle/seed 변이 audit(`p10*`)까지 포함해 결과의 흔들림을 잰다. + +method 선택의 근거는 `DESIGN.md`와 `paper_analysis/`의 dual-lens 분석 14편에 있다. 프레임워크별로 conda env를 격리(`env/`)해 의존성 충돌을 막는다. + +## 6. 게이트 — 자동화가 넘지 못하는 선 + +이 랩은 전부를 자동으로 밀지 않는다. 두 종류의 게이트가 있다. + +**검증 게이트(커밋·공개 전).** 헤드라인 숫자를 결정론적으로 재계산해 결과 파일과 대조한다. + +```bash +cd pipeline/hspc-velocity-benchmark/scripts +conda run --no-capture-output -n scv-preprocess python p3_concordance.py +conda run --no-capture-output -n scv-preprocess python p3_crossdataset_concordance.py --dataset human_brain +conda run --no-capture-output -n scv-preprocess python p3_scrambled_null.py +# 출력 숫자를 results/FINDINGS.md 와 대조. 불일치면 멈추고 사람에게 보고. +``` + +**사람 승인 게이트.** 프리프린트·블로그 외부 공개와 main 병합은 사람이 승인한다. 저자·소속·IP·corresponding email이 확정되기 전에는 공개를 보류한다(원고에 ``로 표시). 작업 브랜치 `kkkim-pipeline`에 대한 커밋·push는 자동으로 수행하되, 이 검증·공개 게이트는 유지한다. + +claim 자체에도 게이트가 있다. headline claim은 반증기준, 가장 값싼 make-or-break 검정, advisor 확인을 통과하기 전에는 PROVISIONAL로 두고 본문에 넣지 않는다. within-method 적합 품질을 cross-method 재현성으로 승격하지 않는다는 규율(2층 융합 금지)도 여기에 든다. diff --git a/ai_scientist/03_multi_ai_collaboration.md b/ai_scientist/03_multi_ai_collaboration.md new file mode 100644 index 0000000..f82cf55 --- /dev/null +++ b/ai_scientist/03_multi_ai_collaboration.md @@ -0,0 +1,118 @@ +# 03. 레이어 B — 멀티 AI 협업 인계 (여러 AI가 팀으로 이어달리기) + +팀원마다 다른 AI(Claude, Codex, Gemini)를 쓰고 결과물은 JIRA·Confluence·Git으로 공유한다. 문제는 한 작업이 끝나도 다음 담당자의 AI에 신호가 자동으로 가지 않는다는 점이다. 사람이 확인할 때까지 대기가 생기고 인계가 지연된다. + +이 레이어는 그 인계를 자동화한다. 설계 문서는 두 편이다. + +- `guide/ai-handoff-architecture-guide.md`: **무엇을** 인계하나. JIRA 상태 전환 신호에서 다음 AI 실행까지의 4계층 구조. +- `guide/openclaw-claude-guide.md`: **어떻게 싸고 안정적으로** 돌리나. OpenClaw와 메시지 큐로 그 구조를 실현하고 비용을 통제하는 방법. + +## 1. 설계 원칙 + +| 원칙 | 내용 | +| --- | --- | +| 단일 신호원 | 인계 신호는 JIRA 상태 전환만 쓴다. Git 머지 등은 JIRA 상태로 수렴시킨다 | +| 사람 승인 우선 | 초기엔 Slack 원클릭 승인 후 실행. 신뢰가 쌓이면 단계적으로 자동화 | +| 최소 권한 | AI별 서비스 계정 분리, 프로젝트 단위 권한, main 직접 push 금지 | +| 폭주 방지 | 티켓당 자동 인계 횟수 상한(기본 5회), 실패 시 즉시 사람 에스컬레이션 | + +## 2. 4계층 아키텍처 + +``` +① 이벤트 소스 (기존 스택) + JIRA 상태 전환(Ready for AI) / Git PR 머지 → JIRA 상태 자동 전환 + │ Webhook (JIRA Automation → HTTP POST) + ▼ +② 이벤트 허브 (신규) + Webhook 수신 → Next Agent 필드로 분기 → (선택) Slack 승인 → 워커 호출 + 실패 시 ai-failed 라벨 + Slack 알림 + │ Execute / SSH / HTTP + ▼ +③ AI 워커 (신규) + run_agent.sh + ├ claude -p ... (Claude Code headless) + ├ codex exec ... (Codex CLI 비대화) + └ gemini -p ... (Gemini CLI 비대화) + │ MCP (공통 mcp.json) + ▼ +④ MCP 공통 + Atlassian 원격 MCP → JIRA 이슈·코멘트·상태, Confluence + GitHub MCP → 저장소, PR, 이슈 + +작업 완료 → AI가 MCP로 JIRA 상태 전환 → 다시 ①의 신호 발생 → 체인 반복 +``` + +### 인계 루프 (티켓 생애주기) + +1. AI나 사람이 작업을 완료한다. 커밋·PR·문서와 함께 **Handoff 코멘트**를 남긴다. +2. JIRA 상태를 `Ready for AI`로 전환하고 `Next Agent` 필드를 지정한다. +3. JIRA Automation이 이벤트 허브로 웹훅을 보낸다. +4. 허브가 `Next Agent` 값으로 분기하고, 초기엔 Slack 승인을 거친다. +5. 해당 AI 워커가 실행되어 MCP로 티켓·코드 맥락을 읽고 작업한다. +6. 완료하면 1번으로 돌아간다. 체인이 이어진다. + +## 3. Handoff 코멘트 — 인계 맥락의 정형화 + +모든 AI의 규칙 파일(CLAUDE.md / AGENTS.md / GEMINI.md)에 같은 템플릿을 강제한다. + +```markdown +## Handoff +- 완료한 것: (요약 3줄 이내) +- 산출물: (커밋 해시 / PR 링크 / Confluence 페이지 링크) +- 다음 작업: (다음 AI가 해야 할 일, 구체적으로) +- 제약/주의: (건드리면 안 되는 것, 실패했던 접근) +- Next Agent: claude | codex | gemini | human +``` + +기준은 하나다. **다음 워커가 이 코멘트 하나만 읽어도 착수할 수 있어야 한다.** 이것이 레이어 A의 산출물 계약과 같은 발상이다. A는 파일로, B는 JIRA 코멘트로 맥락을 넘긴다. + +## 4. 공통 MCP — 모든 AI가 같은 방식으로 읽고 쓴다 + +`mcp.json` 하나를 설정 전용 저장소(`agent-config`)로 버전 관리하고, 세 AI에 같은 서버 정의를 물린다. 연결 대상은 Atlassian 원격 MCP(JIRA·Confluence)와 GitHub MCP다. 세 도구 모두 MCP 표준을 따르므로 서버 정의는 그대로 재사용하고 파일 형식만 각 도구에 맞게 바꾼다. 토큰은 파일에 직접 쓰지 않고 환경변수·시크릿 매니저로 주입한다. + +## 5. OpenClaw로 실현하기 — 허브와 워커를 대체 + +`ai-handoff-architecture-guide.md`는 이벤트 허브로 n8n을, 워커로 공용 서버의 `run_agent.sh`를 상정한다. `openclaw-claude-guide.md`는 그 ②+③(허브+워커)을 **OpenClaw와 메시지 큐로 대체**하는 경로를 제시한다. 별도 n8n·워커 서버를 세우지 않고 같은 인계 루프를 돌린다. + +| 인계 가이드 계층 | 원 구성 | OpenClaw로 실현 | +| --- | --- | --- | +| ① 이벤트 소스 | JIRA 상태 전환 / PR 머지 | 그대로 유지 | +| ② 이벤트 허브 | n8n | 메시지 큐 브리지 + OpenClaw Webhooks 플러그인 | +| ③ AI 워커 | 공용 서버 + `run_agent.sh` + `claude -p` | OpenClaw 세션(인증·모델선택·thinking 레벨을 OpenClaw가 관장) | +| ④ MCP 공통 | `mcp.json` | 동일. OpenClaw 세션에도 같은 MCP 서버를 물린다 | + +허브를 n8n으로 갈지 OpenClaw 웹훅+큐로 갈지는 팀 규모로 정한다. GUI 워크플로와 Slack 승인 버튼이 필요하면 n8n, 비용 통제를 한곳에서 하고 워커 서버 관리를 줄이고 싶으면 OpenClaw다. + +메시지 큐를 앞에 두는 이유는 안정성과 비용이다. 웹훅을 허브에 직결하면 허브가 재시작 중일 때 이벤트를 잃는다. 큐는 고속 이벤트 유입과 느린 Claude 처리를 분리한다. 브리지 컨슈머가 지켜야 할 네 가지는 다음과 같다. + +1. **ack는 Claude 처리 성공 이후에만.** 실패하면 ack하지 않고 데드레터큐로 격리한다. 이것이 인계 가이드의 "실패 시 상태 유지·자동 재시도 금지"를 자연히 만족한다. +2. **동시 처리 수 제한.** 레이트 리밋과 비용을 통제한다. +3. **멱등성·세션 키.** 재시도가 중복 인계를 만들지 않게 한다. +4. **병합(coalescing).** 같은 티켓의 연속 이벤트를 하나로 합쳐 Claude 호출 수 자체를 줄인다. + +## 6. 비용 — 인계 체인은 호출을 곱셈으로 늘린다 + +AI-to-AI 인계는 한 티켓이 여러 AI를 연쇄 호출하므로 단발 실행보다 토큰 지출이 배로 뛴다. 그래서 비용 레버가 인계 자동화에서 더 중요해진다. + +1. **병합**: 같은 티켓에 상태전환·코멘트 이벤트가 쏟아져도 브리지가 하나로 합쳐 호출 1회로. +2. **모델 티어링**: 저위험 작업(리뷰·테스트·문서화)은 Sonnet/Haiku로, 핵심 분석만 Opus로. `Next Agent`별로 모델을 다르게 물린다. +3. **프롬프트 캐싱**: 티켓 단위 sessionKey로 인계 맥락을 재사용해 입력 토큰을 줄인다. +4. **우선순위 큐**: 비싼 Opus 인계와 값싼 Sonnet 인계를 다른 큐로 분리 라우팅한다. +5. **DLQ**: poison 티켓이 무한 재인계로 과금되는 것을 막는다. + +## 7. 보안·승인 게이트 + +- **승인 게이트**: 도입 초기엔 Slack 승인 필수. OpenClaw 경로에서는 브리지가 큐→OpenClaw POST 직전에 Slack "Send-and-Wait"를 두거나, 웹훅을 수동 트리거로 둔다. +- **최소 권한**: AI별 서비스 계정 분리, JIRA는 해당 프로젝트만, main 직접 push 금지(브랜치+PR). +- **서명 검증 2구간**: JIRA Automation의 `X-Handoff-Token`과 OpenClaw webhook `secret`을 둘 다 건다. 이벤트 소스와 브리지 사이, 브리지와 OpenClaw 사이를 모두 검증한다. +- **토큰 비노출**: API 키·PAT는 환경변수·시크릿 매니저로만. `.mcp.json`에 토큰 직접 기입 금지. + +## 8. 도입 로드맵 + +| 주차 | 목표 | 산출물 | +| --- | --- | --- | +| 1주차 | JIRA 필드·워크플로·Automation + 허브 설치, Slack 알림까지만 | 인계 발생 즉시 알림(자동 실행 없음) | +| 2~3주차 | AI CLI·MCP 공통 설정·워커 구축, Slack 승인 후 반자동 | 첫 AI-to-AI 인계 파일럿 1건 | +| 4주차~ | 저위험 작업부터 승인 생략, 인계 상한·모니터링 정착 | 제한적 완전 자동 체인 + 비용 레버 계측 | + +설치 절차 전체는 `guide/ai-handoff-architecture-guide.md` §4에, OpenClaw판 세부는 `guide/openclaw-claude-guide.md` §3에 있다. diff --git a/ai_scientist/04_design_principles.md b/ai_scientist/04_design_principles.md new file mode 100644 index 0000000..d73a7a2 --- /dev/null +++ b/ai_scientist/04_design_principles.md @@ -0,0 +1,59 @@ +# 04. 설계 원칙 — 두 레이어를 관통하는 것 + +레이어 A(단일 랩 자동화)와 레이어 B(멀티 AI 인계)는 다른 문제를 풀지만 같은 원리 위에 서 있다. 이 원리들이 AI Scientist 설계의 뼈대다. + +## 1. 다음 주체가 하나만 읽어도 착수할 수 있게 한다 + +두 레이어 모두 작업 맥락을 대화가 아니라 **정형화된 산출물**로 넘긴다. + +- 레이어 A: 결과 파일(`results/FINDINGS.md`), 원고(`draft_v2.md`), 상태 문서(`HANDOFF.md`). +- 레이어 B: JIRA Handoff 코멘트(완료한 것·산출물·다음 작업·제약·Next Agent). + +기준은 같다. 다음 멤버나 다음 AI가 그 산출물 하나만 읽으면 곧바로 일을 시작할 수 있어야 한다. 이 규율이 있어 멤버가 바뀌거나 세션이 끊겨도 작업이 이어지고, 매번 처음부터 다시 브리핑할 필요가 없다. + +## 2. 자동화하되 사람 게이트를 남긴다 + +전부를 자동으로 밀지 않는다. 되돌리기 어렵거나 외부로 나가는 지점에는 사람이 선다. + +- 레이어 A: 프리프린트·블로그 공개와 main 병합은 사람이 승인한다. 저자·소속·corresponding email이 확정되기 전에는 공개를 보류한다. +- 레이어 B: 도입 초기엔 모든 인계에 Slack 승인을 건다. 신뢰가 쌓이면 저위험 작업부터 단계적으로 승인을 생략한다. + +승인 게이트는 고정이 아니라 성숙도에 따라 옮긴다. 처음엔 촘촘하게, 검증되면 넓게. 이 단계적 완화가 두 레이어에 공통으로 들어 있다. + +## 3. 검증 게이트로 근거 없는 주장을 막는다 + +자동화가 그럴듯하지만 틀린 결과를 통과시키지 않도록, 커밋·공개 전에 숫자를 다시 계산해 대조한다. + +- 레이어 A: 헤드라인 숫자를 결정론적 스크립트로 재계산해 결과 파일과 대조하고, 불일치하면 멈추고 사람에게 보고한다. claim 자체도 반증기준·make-or-break 검정·advisor 확인을 통과하기 전에는 본문에 넣지 않는다. +- weak는 zero가 아니다. 통계가 뒷받침하지 않는 우월·재현 주장을 금지한다. + +## 4. 폭주와 비용을 구조로 막는다 + +AI 체인은 스스로를 무한히 호출하거나 토큰을 쏟아낼 수 있다. 이걸 사람의 주의가 아니라 구조로 막는다. + +- 레이어 B: 티켓당 자동 인계 상한(Hop Count < 5), 실패 메시지의 DLQ 격리, 동시 처리 수 제한. +- 비용 레버: 이벤트 병합, 모델 티어링(저위험은 Sonnet/Haiku, 핵심만 Opus), 프롬프트 캐싱, 우선순위 큐. + +인계 체인은 한 티켓이 여러 AI를 거치며 호출을 곱셈으로 늘리므로, 이 레버들이 단발 실행보다 더 중요해진다. + +## 5. 최소 권한과 격리 + +- AI별 서비스 계정을 분리해 JIRA·Git 이력을 추적한다. +- JIRA는 해당 프로젝트만, GitHub는 PR 권한만 준다. +- main 브랜치 직접 push를 금지하고 항상 브랜치와 PR로 간다. +- 자동 승인 옵션(`--permission-mode acceptEdits`, `--yolo`)은 격리된 작업 디렉토리와 최소 권한 계정을 전제로만 쓴다. +- 토큰·API 키는 코드나 코멘트에 남기지 않고 환경변수·시크릿 매니저로만 관리한다. + +## 6. 표준 포맷과 재사용 + +멤버 정의와 라우터를 특정 프로젝트에 묶지 않고 재사용할 수 있게 만들었다. + +- 논문 생산 하네스는 재사용 스캐폴드(CC BY 4.0)로 설계했고, 도메인 전용 슬롯 하나(`hspc-velocity-analyst`)만 이 프로젝트가 채웠다. +- 분석 하네스는 OpenClaw/Codex 네이티브 포맷(`AGENTS.md` + `skills/ROUTES.md` + `openai.yaml`)을 유지해 OpenClaw로 바로 실행하고 Claude Code에서도 동작한다. +- MCP 표준을 따르므로 서버 정의를 세 AI가 그대로 재사용한다. + +이 표준화가 있어 새 데이터셋·새 논문·다른 AI로 옮겨도 구조를 다시 짜지 않는다. + +## 7. 근거와 코드를 분리한다 + +이 프로젝트는 method 선택의 **근거**(`paper_analysis/`의 dual-lens 분석 14편)와 그 근거로 데이터를 돌리는 **코드**(`pipeline/`)를 한 브랜치, 두 폴더로 나눴다. 어떤 method와 confound를 쓸지의 판단(근거)과 실제 실행(코드)을 섞지 않아, 판단이 바뀌면 근거 레이어만, 실행이 바뀌면 코드 레이어만 고친다. diff --git a/ai_scientist/05_component_map.md b/ai_scientist/05_component_map.md new file mode 100644 index 0000000..ef66b81 --- /dev/null +++ b/ai_scientist/05_component_map.md @@ -0,0 +1,51 @@ +# 05. 컴포넌트 매핑 — 설계 요소가 저장소 어디에 있나 + +AI Scientist 설계의 각 요소가 실제로 어느 파일에 구현·문서화돼 있는지 정리한 지도다. 이 폴더(`ai_scientist/`)는 설계를 **설명**하고, 아래 파일들이 그 설계를 **구현**한다. + +## 레이어 A — 단일 랩 자동화 + +| 설계 요소 | 저장소 위치 | +| --- | --- | +| 랩 구조 지도(멤버 명부·관계도·JD) | `docs/HARNESS.md` | +| 라우팅표 + 산출물 계약 요약 | `CLAUDE.md` (*Agent routing & artifact contract* 절) | +| 멤버 정의 8종 | `.claude/agents/{hspc-velocity-analyst,literature-scout,novelty-strategist,research-methodologist,manuscript-writer,presenter,paper-critic,paper-orchestrator,design}.md` | +| 오케스트레이터(실행 입구) | `.claude/skills/paper-production-orchestrator/SKILL.md` | +| 단일 컨텍스트(thesis·claim 등급표·loop 규율) | `pipeline/hspc-velocity-benchmark/manuscript/PAPER_DIRECTION.md` | +| 분석 실행 엔진(P0–P5) | `pipeline/hspc-velocity-benchmark/scripts/` (`download_data.sh`, `p1_build.py`, `p2_*.py`, `p3_*.py`, `p10*` 등) | +| method 선택 근거 | `pipeline/hspc-velocity-benchmark/DESIGN.md`, `paper_analysis/`(dual-lens 14편) | +| 실험 env 격리 | `pipeline/hspc-velocity-benchmark/env/` | +| 분석 산출물 계약 | `pipeline/hspc-velocity-benchmark/results/FINDINGS.md` + `results/*.csv` + `results/*.md` | +| 집필·그림 산출물 | `pipeline/hspc-velocity-benchmark/manuscript/draft_v2{,_ko}.md`, `figures/figNN_*.py` | +| 검수·리뷰 산출물 | `manuscript/REVIEW--.md` | +| 검증 게이트 스크립트 | `scripts/p3_concordance.py`, `p3_crossdataset_concordance.py`, `p3_scrambled_null.py` | +| 글쓰기 규율(한국어 윤문) | `.claude/rules/writing-style.md` | +| 상태 핸드오프 | `HANDOFF.md`, `TODO.md`, `SESSION-LOG.md` | + +## 레이어 B — 멀티 AI 협업 인계 + +| 설계 요소 | 저장소 위치 | +| --- | --- | +| 인계 아키텍처(4계층·인계 루프·설치 가이드) | `guide/ai-handoff-architecture-guide.md` | +| OpenClaw 실현(허브+워커 대체·메시지 큐·비용 레버) | `guide/openclaw-claude-guide.md` | +| 분석 하네스 project frame(OpenClaw/Codex 네이티브 포맷) | `AGENTS.md` (dataset 라우팅을 `skills/ROUTES.md`에 위임) | +| dataset→task 스킬 트리(`skills/ROUTES.md`, `skills///{SKILL.md,agents/openai.yaml}`) | 이 브랜치 체크아웃에는 없다. `AGENTS.md`·`README.md`가 규정하는 포맷이며, 실제 스킬 트리는 OpenClaw로 돌릴 때 채운다 | +| MCP 공통 설정 | `.mcp.json` (설계 목표는 `agent-config` 저장소로 버전 관리) | +| 팀·역할·AI 계정 매핑 | `Project-Info.md` (데이터셋 담당자 ↔ github·atlassian·slack·openclaw bot) | +| JIRA·Confluence 좌표 | `Project-Info.md` (JIRA space `BIOP01`, Confluence space `VC`) | + +## 두 레이어의 접점 + +| 공유 요소 | 레이어 A에서 | 레이어 B에서 | +| --- | --- | --- | +| 인계 계약 | 결과 파일(`results/FINDINGS.md`) | JIRA Handoff 코멘트 | +| 사람 게이트 | 공개·main 병합 승인 | 초기 Slack 승인 | +| 폭주·비용 방지 | 검증 게이트, claim 등급 | Hop Count 상한, 큐·DLQ, 모델 티어링 | +| 실행 도구 | Claude Code(agent·Skill) | OpenClaw 세션 또는 `run_agent.sh` | +| 라우터 포맷 | `CLAUDE.md` 라우팅표 | `Next Agent` 필드 → 브리지 분기 | + +## 읽는 순서 제안 + +1. 전체 그림만 빠르게: 이 폴더 [README.md](README.md)와 [01_overview.md](01_overview.md). +2. 단일 랩이 어떻게 도나: [02_single_lab_harness.md](02_single_lab_harness.md) → `docs/HARNESS.md` → `.claude/skills/paper-production-orchestrator/SKILL.md`. +3. 여러 AI가 어떻게 이어달리나: [03_multi_ai_collaboration.md](03_multi_ai_collaboration.md) → `guide/ai-handoff-architecture-guide.md` → `guide/openclaw-claude-guide.md`. +4. 왜 이렇게 설계했나: [04_design_principles.md](04_design_principles.md). diff --git a/ai_scientist/README.md b/ai_scientist/README.md new file mode 100644 index 0000000..d1c4d1a --- /dev/null +++ b/ai_scientist/README.md @@ -0,0 +1,48 @@ +# ai_scientist/ — AI Scientist 설계 정리 + +이 폴더는 이번 프로젝트에서 **AI Scientist**(인공지능이 연구 도구를 넘어 연구 과정 전반을 자동화하고, 여러 연구자가 함께 쓰도록 만든 구조)를 어떻게 설계했는지 한곳에 정리한 문서다. 새 코드를 만드는 것이 아니라, `kkkim-pipeline` 브랜치에 이미 흩어져 구현·기록된 설계를 확인해 하나의 지도로 묶었다. + +## 무엇을 다루나 + +목표는 두 가지였다. + +1. **연구 과정 전반의 자동화**: 논문 탐색과 정리, 가설 설정, 실험 수행, 그림·집필, 검수, 발표까지를 사람이 매 단계 손으로 잇지 않고 하나의 흐름으로 돌린다. +2. **여러 연구자와 협업하는 구조**: 팀원마다 다른 AI(Claude, Codex, Gemini)를 쓰더라도, 작업을 서로에게 자동으로 넘기고 이어받는 인계 체계를 표준화한다. + +이 두 목표는 각각 하나의 레이어로 설계했고, 서로 맞물린다. + +| 레이어 | 무엇인가 | 이 저장소의 구현·근거 | +| --- | --- | --- | +| **A. 단일 랩 자동화** | 한 연구자의 연구 과정 전체를 agent 멤버들이 나눠 맡아 자동으로 돌리는 "AI 연구 랩" | `.claude/agents/` 8종 + `paper-production-orchestrator` Skill + `AGENTS.md`/`skills/` 라우터 + 파이프라인 `scripts/`(P0–P5). 지도 = `docs/HARNESS.md` | +| **B. 멀티 AI 협업 인계** | 여러 연구자·여러 AI가 JIRA 상태 신호로 작업을 자동 인계하는 체계 | `guide/ai-handoff-architecture-guide.md` + `guide/openclaw-claude-guide.md` | + +레이어 A는 "AI 한 명이 논문 한 편을 어떻게 끝까지 끌고 가나"를, 레이어 B는 "그런 AI 여럿이 팀으로 어떻게 이어달리나"를 설계한다. A가 랩 안의 분업이라면 B는 랩과 랩, 사람과 사람 사이의 배턴 터치다. + +## 문서 구성 + +- [01_overview.md](01_overview.md) — AI Scientist가 무엇을 자동화하는지와 전체 그림 +- [02_single_lab_harness.md](02_single_lab_harness.md) — 레이어 A: 단일 랩 자동화(멤버 명부, 논문 생산 루프, 파이프라인, 게이트) +- [03_multi_ai_collaboration.md](03_multi_ai_collaboration.md) — 레이어 B: 멀티 AI 인계 자동화(JIRA→허브→워커→MCP, OpenClaw+큐) +- [04_design_principles.md](04_design_principles.md) — 두 레이어를 관통하는 설계 원칙 +- [05_component_map.md](05_component_map.md) — 설계 요소와 실제 저장소 파일의 매핑 + +## 한눈에 보는 전체 그림 + +``` + 사람 = PI (방향 설정 · 승인 · 공개 게이트) + │ + ┌───────────────────────────┴───────────────────────────┐ + │ │ + 레이어 A: 단일 랩 자동화 레이어 B: 멀티 AI 협업 인계 + (한 AI가 논문 한 편을 끝까지) (여러 AI가 팀으로 이어달리기) + │ │ + paper-production-orchestrator (Skill) JIRA 상태 전환(Ready for AI) + │ ↓ 멤버 호출 │ ↓ Automation 웹훅 + 기획 → 분석 → 집필·그림 → 검수 → 발표 이벤트 허브(n8n 또는 OpenClaw+큐) + │ ↓ 산출물 계약(파일로 인계) │ ↓ Next Agent 분기 + results/ · manuscript/ · figures/ AI 워커(claude/codex/gemini) + │ ↓ 검증 게이트(숫자 재계산) │ ↓ 공통 MCP(JIRA·GitHub) + 사람 승인 → 공개 Handoff 코멘트 → 다음 AI (체인) +``` + +두 레이어의 접점은 **산출물 계약**과 **Handoff 규율**이다. 레이어 A의 멤버가 결과를 파일로 남기는 규율(results/FINDINGS.md 등)과, 레이어 B의 AI가 JIRA에 Handoff 코멘트를 남기는 규율은 같은 발상이다. 다음에 일할 주체가 그 산출물 하나만 읽어도 곧바로 착수할 수 있게 만든다. diff --git a/ai_scientist/output_v01/README.md b/ai_scientist/output_v01/README.md new file mode 100644 index 0000000..4292a45 --- /dev/null +++ b/ai_scientist/output_v01/README.md @@ -0,0 +1,25 @@ +# output_v01 — AI Scientist 설계 시각화 (HTML + mermaid) + +`ai_scientist/`의 마크다운 6편(README, 01–05)을 하나의 인터랙티브 HTML 문서로 묶은 결과물이다. + +## 여는 법 + +`index.html`을 브라우저로 열면 된다. + +```bash +# 예: 로컬에서 바로 열기 +xdg-open ai_scientist/output_v01/index.html # Linux +open ai_scientist/output_v01/index.html # macOS +``` + +## 구성 + +- **단일 페이지**: 좌측 사이드바 목차 + 본문. 개요 → 레이어 A → 레이어 B → 설계 원칙 → 컴포넌트 맵. +- **mermaid 다이어그램 6종**: 전체 그림, 랩 조직도, 논문 생산 루프, 파이프라인 P0–P5, 4계층 아키텍처, 인계 루프. +- **라이트/다크 테마 토글**(좌측 하단 버튼). 시스템 설정도 자동 반영. + +## 알아둘 점 + +- mermaid 라이브러리를 CDN(jsdelivr)에서 불러온다. 따라서 **다이어그램 렌더에는 인터넷 연결이 필요**하다. 표·본문은 오프라인에서도 보인다. +- 완전 오프라인(자체 완결형)이 필요하면 mermaid를 파일에 인라인하는 버전으로 다시 만들 수 있다. +- 다이어그램 6종은 mermaid 파서로 문법 검증을 마쳤다. diff --git a/ai_scientist/output_v01/index.html b/ai_scientist/output_v01/index.html new file mode 100644 index 0000000..798e27b --- /dev/null +++ b/ai_scientist/output_v01/index.html @@ -0,0 +1,507 @@ + + + + + +AI Scientist 설계 — BioProject01 / kkkim-pipeline + + + + +
+ + +
+
+ + +
+
설계 정리 · Design Overview
+

AI Scientist — 연구 과정 전반의 자동화와 멀티 연구자 협업 구조

+

인공지능이 연구 도구를 넘어, 논문 탐색·정리부터 가설 설정, 실험 수행, 논문 작성까지 연구 과정 전반을 자동화하고, 여러 연구자가 함께 쓰도록 만든 구조를 두 개의 레이어로 정리한다.

+

이 문서는 ai_scientist/ 안의 마크다운 6편을 mermaid 다이어그램과 함께 시각화한 것이다. 새 설계가 아니라, kkkim-pipeline 브랜치에 이미 구현·기록된 구조를 하나의 지도로 묶었다.

+
+ + +
+

◆개요 — 두 개의 레이어

+

목표는 두 가지였고, 각각 하나의 레이어로 설계했다. 레이어 A는 "AI 한 명이 논문 한 편을 어떻게 끝까지 끌고 가나"를, 레이어 B는 "그런 AI 여럿이 팀으로 어떻게 이어달리나"를 설계한다. A가 랩 안의 분업이라면 B는 랩과 랩, 사람과 사람 사이의 배턴 터치다.

+ +
+ + + +
레이어무엇인가이 저장소의 구현·근거
A 단일 랩 자동화한 연구자의 연구 과정 전체를 agent 멤버들이 나눠 맡아 자동으로 돌리는 "AI 연구 랩".claude/agents/ + paper-production-orchestrator Skill + 파이프라인 scripts/. 지도 = docs/HARNESS.md
B 멀티 AI 협업 인계여러 연구자·여러 AI가 JIRA 상태 신호로 작업을 자동 인계하는 체계guide/ai-handoff-architecture-guide.md + guide/openclaw-claude-guide.md
+ +
+

그림 1. 전체 그림 — 사람(PI) 아래 두 레이어가 산출물 계약과 Handoff 규율로 맞물린다

+ 
+flowchart TB
+  PI["사람 = PI
방향 설정 · 승인 · 공개 게이트"]
+  PI --> LA
+  PI --> LB
+  subgraph LA["레이어 A · 단일 랩 자동화"]
+    direction TB
+    A1["paper-production-orchestrator (Skill)"]
+    A2["기획 · 분석 · 집필/그림 · 검수 · 발표"]
+    A3["산출물 계약: results / manuscript / figures"]
+    A1 --> A2 --> A3
+  end
+  subgraph LB["레이어 B · 멀티 AI 협업 인계"]
+    direction TB
+    B1["JIRA 상태 전환 (Ready for AI)"]
+    B2["이벤트 허브 (n8n 또는 OpenClaw+큐)"]
+    B3["AI 워커: claude / codex / gemini"]
+    B4["공통 MCP (JIRA · GitHub)"]
+    B1 --> B2 --> B3 --> B4
+  end
+  A3 -->|"공유: 산출물 계약"| SH
+  B4 -->|"공유: Handoff 규율"| SH
+  SH["다음 주체가 산출물 하나만 읽어도 곧바로 착수"]
+  classDef pi fill:#0e7c86,stroke:#0e7c86,color:#fff;
+  classDef share fill:#b26a00,stroke:#b26a00,color:#fff;
+  class PI pi;
+  class SH share;
+
+
+
+ + +
+

01연구 과정을 어떤 단계로 나눴나

+

전통적인 연구 흐름을 AI가 맡을 수 있는 단계로 나누면 일곱 단계가 된다. 사람이 도구를 하나씩 손으로 돌리는 대신, AI 멤버들이 각 단계를 나눠 맡아 이어서 돌아가게 한다.

+
+ + + + + + + + +
#단계담당 주체
1논문 탐색·정리 (정직한 포지셔닝)literature-scout, paper_analysis/ dual-lens 14편
2가설 설정·차별화 (가장 값싼 입증)novelty-strategist, research-methodologist
3실험 설계·감사 (누수·통계 위험 차단)research-methodologist
4실험 수행·분석 (eval·통계·cross-dataset)hspc-velocity-analyst + scripts/ P0–P5
5집필·그림manuscript-writer + figures/figNN_*.py
6검수·리뷰paper-critic, reviewer
7발표presenter
+

일곱 단계를 사람이 매번 순서대로 부르지 않도록, 자연어 요청을 멤버에 배정하는 라우팅표(CLAUDE.md)와 여러 단계를 엮어 실행하는 오케스트레이터 Skill을 두었다.

+
+ + +
+

02레이어 A 단일 랩 자동화

+

agent는 직원이 아니라 랩의 멤버(연구원)이고, 사람과 메인 루프가 랩을 이끄는 PI다. PI는 무엇을 할지 정하고 승인·공개를 책임지되, 실제 작업은 멤버가 파일로 주고받으며 이어서 한다.

+ +

멤버 명부

+

하나(hspc-velocity-analyst)만 이 프로젝트 도메인 전용이고, 나머지는 다른 논문에도 재사용할 수 있게 만들었다.

+
+ + + + + + + + + + + + +
멤버벤치역할
hspc-velocity-analyst분석실도메인 슬롯. 파이프라인(P0–P5)·eval·통계·cross-dataset 실행, 결과 파일 유지
literature-scout문헌·기획선행연구 탐색, 정직한 포지셔닝, related work
novelty-strategist문헌·기획차별화 각도와 가장 값싼 입증 실험 제안
research-methodologist문헌·기획가설·기여문·실험설계, 누수·통계 감사
manuscript-writer집필실프리프린트·저널·블로그 본문 초안과 그림 연계
presenter집필실청중 맞춤 슬라이드·발제
paper-critic심사·QA제출 전 적대적 자체검토와 그림 시각 QA
reviewer심사·QA정식 venue 스타일 공식 리뷰 (선택)
paper-orchestrator코디네이션멀티 agent 작업의 계획만 수립 (실행은 PI)
design엔지니어링로고·아이콘·브랜드·그림 미감
그림 생성 스크립트엔지니어링figures/figNN_*.py — 결과 파일에서 그림 생성·번호 정합
+
그림 생성을 agent가 아니라 결정론적 스크립트로 둔 것이 설계상의 선택이다. 숫자를 손으로 하드코딩하지 않고 결과 파일에서만 뽑게 해 재현성을 지킨다.
+ +
+

그림 2. 랩 조직도 — PI 아래 다섯 벤치에 멤버가 배치된다

+ 
+flowchart TB
+  PI["PI = 사람 + 메인 루프"]
+  ORC["paper-orchestrator
(계획만)"]
+  PI --> ORC
+  ORC --> G1 & G2 & G3 & G4 & G5
+  subgraph G1["문헌·기획"]
+    m1["literature-scout"]; m2["novelty-strategist"]; m3["research-methodologist"]
+  end
+  subgraph G2["분석실"]
+    m4["hspc-velocity-analyst"]
+  end
+  subgraph G3["집필실"]
+    m5["manuscript-writer"]; m6["presenter"]
+  end
+  subgraph G4["심사·QA"]
+    m7["paper-critic"]; m8["reviewer (선택)"]
+  end
+  subgraph G5["엔지니어링"]
+    m9["design"]; m10["figNN_*.py 스크립트"]
+  end
+  classDef pi fill:#0e7c86,stroke:#0e7c86,color:#fff;
+  class PI pi;
+
+
+
+ +
+

자연어 라우팅과 오케스트레이터

+

요청에 agent 이름이 없어도 CLAUDE.md의 라우팅표가 자연어 요청을 멤버에 배정한다. 여러 단계를 엮는 요청("분석→집필→그림→검수까지", "critic 지적 반영해")은 단일 멤버가 아니라 paper-production-orchestrator Skill로 보낸다. 메인 루프(PI)가 이 Skill을 실행하며 멤버를 순서대로 부른다. subagent는 subagent를 못 부르므로, "계획만 짜는" paper-orchestrator agent와 달리 실제 실행은 이 Skill이 맡는다.

+ +
+

그림 3. 논문 생산 루프 — 검증 게이트를 통과해야 발표·공개로 넘어간다

+ 
+flowchart LR
+  P["기획·근거
methodologist · scout · strategist"] --> AN["분석·eval
hspc-velocity-analyst"]
+  AN --> WR["집필+그림
manuscript-writer"]
+  WR --> CR["검수
paper-critic"]
+  CR -->|"블로킹 지적"| WR
+  CR --> VG{"검증 게이트
숫자 재계산"}
+  VG -->|"불일치"| STOP["멈춤 · 사람 보고"]
+  VG -->|"통과"| PR["발표
presenter"]
+  classDef gate fill:#b26a00,stroke:#b26a00,color:#fff;
+  classDef stop fill:#b3261e,stroke:#b3261e,color:#fff;
+  class VG gate; class STOP stop;
+
+
+

핵심은 부분 재실행이다. 이미 만들어진 산출물이 있으면 요청한 단계만 다시 돌리고 나머지는 기존 파일을 재사용한다. "그림만 다시"면 집필+그림 단계만, "최신 결과로 본문 갱신"이면 변경 지점의 하류 단계만 돌린다.

+
+ +
+

산출물 계약 — 대화가 아니라 파일로 넘긴다

+

멤버는 중간 결과를 대화에만 남기지 않고 정해진 파일로 넘긴다. 다음 멤버는 그 파일을 읽고 이어서 일한다. 이 계약 덕분에 멤버가 교체되거나 세션이 끊겨도 작업이 이어진다.

+
+ + + + + + +
단계Writer산출물다음이 읽음
분석·evalhspc-velocity-analystresults/FINDINGS.md + results/*.csv + results/*.md집필·검수
집필·그림manuscript-writermanuscript/draft_v2.md + draft_v2_ko.md (영/한 동시), figures/*.png검수·리뷰·발표
검수·리뷰paper-critic / reviewermanuscript/REVIEW-<venue>-<date>.md집필(수정)
발표presenter슬라이드·발제사람
상태 핸드오프전원HANDOFF.md, TODO.md, SESSION-LOG.md다음 세션
+
+ +
+

실험 실행 엔진 — 파이프라인 P0–P5

+

분석 단계의 실제 계산은 pipeline/hspc-velocity-benchmark/scripts/가 담당한다. hspc-velocity-analyst가 이 스크립트들을 돌려 결과 파일을 만든다.

+
+

그림 4. 파이프라인 단계 — 공통 전처리(P1) 위에서 method를 분기해 재현성을 검증한다

+ 
+flowchart LR
+  P0["P0
다운로드·provenance"] --> P1["P1
통일 전처리"]
+  P1 --> P2["P2
velocity method 실행"]
+  P2 --> P3["P3
재현성 검증"]
+  P3 --> P4["P4
permutation FDR"]
+  P4 --> P5["P5
bootstrap 안정성"]
+
+
+
    +
  • P0 — download_data.sh로 GSE209878를 받고 download_manifest.tsv(sha256)와 P0_provenance.md를 남긴다.
    • +
  • P1 — p1_build.py가 공통 branch를 만든다. 여기서 preprocessing 차이와 method 차이를 분리한다.
    • +
  • P2 — p2_multivelo.py, p2_moflow.py, p2_crakvelo_*, p2_multivelovae.py 등으로 여러 method를 같은 전처리 위에서 돌린다.
    • +
  • P3 — p3_concordance.py, p3_crossdataset_concordance.py, p3_scrambled_null.py로 method 간·dataset 간 일치도와 null을 계산한다.
    • +
  • P4 — gene 단위 다중검정을 permutation FDR로 통제한다.
    • +
  • P5 — shuffle/seed 변이 audit(p10*)까지 포함해 결과의 흔들림을 잰다.
    • +
+
+ +
+

게이트 — 자동화가 넘지 못하는 선

+

이 랩은 전부를 자동으로 밀지 않는다. 두 종류의 게이트가 있다.

+

검증 게이트 (커밋·공개 전). 헤드라인 숫자를 결정론적으로 재계산해 결과 파일과 대조한다.

+ 
cd pipeline/hspc-velocity-benchmark/scripts
+conda run --no-capture-output -n scv-preprocess python p3_concordance.py
+conda run --no-capture-output -n scv-preprocess python p3_crossdataset_concordance.py --dataset human_brain
+conda run --no-capture-output -n scv-preprocess python p3_scrambled_null.py
+# 출력 숫자를 results/FINDINGS.md 와 대조. 불일치면 멈추고 사람에게 보고.
+

사람 승인 게이트. 프리프린트·블로그 외부 공개와 main 병합은 사람이 승인한다. 저자·소속·IP·corresponding email이 확정되기 전에는 공개를 보류한다(<FILL>). claim 자체도 반증기준·make-or-break 검정·advisor 확인을 통과하기 전에는 PROVISIONAL로 두고 본문에 넣지 않는다.

+
+ + +
+

03레이어 B 멀티 AI 협업 인계

+

팀원마다 다른 AI(Claude, Codex, Gemini)를 쓰고 결과물은 JIRA·Confluence·Git으로 공유한다. 문제는 한 작업이 끝나도 다음 담당자의 AI에 신호가 자동으로 가지 않아 인계가 지연된다는 점이다. 이 레이어는 그 인계를 자동화한다.

+
+ + + + + +
원칙내용
단일 신호원인계 신호는 JIRA 상태 전환만 쓴다. Git 머지 등은 JIRA 상태로 수렴시킨다
사람 승인 우선초기엔 Slack 원클릭 승인 후 실행. 신뢰가 쌓이면 단계적으로 자동화
최소 권한AI별 서비스 계정 분리, 프로젝트 단위 권한, main 직접 push 금지
폭주 방지티켓당 자동 인계 상한(기본 5회), 실패 시 즉시 사람 에스컬레이션
+ +
+

그림 5. 4계층 아키텍처 — 작업 완료가 다시 JIRA 상태 전환을 일으켜 체인이 반복된다

+ 
+flowchart TB
+  subgraph L1["① 이벤트 소스 (기존 스택)"]
+    S1["JIRA 상태 전환: Ready for AI"]
+    S2["Git PR 머지 → JIRA 상태 자동 전환"]
+  end
+  subgraph L2["② 이벤트 허브 (신규)"]
+    H1["Webhook 수신 · Next Agent 분기 · (선택) Slack 승인 · 워커 호출"]
+  end
+  subgraph L3["③ AI 워커 (신규)"]
+    W1["claude -p"]; W2["codex exec"]; W3["gemini -p"]
+  end
+  subgraph L4["④ MCP 공통"]
+    M1["Atlassian MCP: JIRA · Confluence"]
+    M2["GitHub MCP: 저장소 · PR"]
+  end
+  L1 -->|"Webhook (HTTP POST)"| L2
+  L2 -->|"Execute / SSH / HTTP"| L3
+  L3 -->|"공통 mcp.json"| L4
+  L4 -.->|"상태 전환 → 신호 재발생"| L1
+
+
+
+ +
+

인계 루프와 Handoff 코멘트

+
+

그림 6. 티켓 생애주기 — 후속 작업이 있으면 1번으로 돌아가 체인이 이어진다

+ 
+flowchart TB
+  T1["1. 작업 완료 + Handoff 코멘트"] --> T2["2. JIRA 상태 Ready for AI · Next Agent 지정"]
+  T2 --> T3["3. Automation 웹훅 발송"]
+  T3 --> T4["4. 허브가 Next Agent로 분기 (초기 Slack 승인)"]
+  T4 --> T5["5. AI 워커 실행: MCP로 맥락 로드 후 작업"]
+  T5 --> T6{"후속 작업?"}
+  T6 -->|"있음 → Ready for AI"| T1
+  T6 -->|"사람 검토 → In Review"| HU["사람"]
+
+
+

모든 AI의 규칙 파일(CLAUDE.md / AGENTS.md / GEMINI.md)에 같은 Handoff 템플릿을 강제한다. 기준은 하나다. 다음 워커가 이 코멘트 하나만 읽어도 착수할 수 있어야 한다. 이것이 레이어 A의 산출물 계약과 같은 발상이다. A는 파일로, B는 JIRA 코멘트로 맥락을 넘긴다.

+ 
## Handoff
+- 완료한 것: (요약 3줄 이내)
+- 산출물: (커밋 해시 / PR 링크 / Confluence 페이지 링크)
+- 다음 작업: (다음 AI가 해야 할 일, 구체적으로)
+- 제약/주의: (건드리면 안 되는 것, 실패했던 접근)
+- Next Agent: claude | codex | gemini | human
+
+ +
+

OpenClaw로 실현하기 — 허브와 워커를 대체

+

인계 가이드는 이벤트 허브로 n8n을, 워커로 공용 서버의 run_agent.sh를 상정한다. OpenClaw 가이드는 그 ②+③(허브+워커)을 OpenClaw와 메시지 큐로 대체하는 경로를 제시한다. 별도 서버를 세우지 않고 같은 인계 루프를 돌린다.

+
+ + + + + +
인계 가이드 계층원 구성OpenClaw로 실현
① 이벤트 소스JIRA 상태 전환 / PR 머지그대로 유지
② 이벤트 허브n8n메시지 큐 브리지 + OpenClaw Webhooks 플러그인
③ AI 워커공용 서버 + run_agent.sh + claude -pOpenClaw 세션 (인증·모델선택·thinking 레벨 관장)
④ MCP 공통mcp.json동일. OpenClaw 세션에도 같은 MCP 서버를 물린다
+

메시지 큐를 앞에 두는 이유는 안정성과 비용이다. 브리지 컨슈머는 네 가지를 지킨다. (1) ack는 Claude 처리 성공 이후에만, (2) 동시 처리 수 제한, (3) 멱등성·세션 키, (4) 같은 티켓 연속 이벤트 병합.

+ +
비용 — 인계 체인은 호출을 곱셈으로 늘린다. 한 티켓이 여러 AI를 연쇄 호출하므로 단발 실행보다 토큰 지출이 배로 뛴다. 그래서 비용 레버가 인계 자동화에서 더 중요해진다: 이벤트 병합, 모델 티어링(저위험은 Sonnet/Haiku, 핵심만 Opus), 티켓 단위 프롬프트 캐싱, 우선순위 큐, poison 티켓의 DLQ 격리.

+
+ +
+

보안·승인 게이트와 도입 로드맵

+
    +
  • 서명 검증 2구간 — JIRA Automation의 X-Handoff-Token과 OpenClaw webhook secret을 둘 다 건다.
    • +
  • 최소 권한 — AI별 서비스 계정 분리, JIRA는 해당 프로젝트만, main 직접 push 금지(브랜치+PR).
    • +
  • 토큰 비노출 — API 키·PAT는 환경변수·시크릿 매니저로만. .mcp.json에 토큰 직접 기입 금지.
    • +
+
+ + + + +
주차목표산출물
1주차JIRA 필드·워크플로·Automation + 허브 설치, Slack 알림까지만인계 발생 즉시 알림 (자동 실행 없음)
2~3주차AI CLI·MCP 공통 설정·워커 구축, Slack 승인 후 반자동첫 AI-to-AI 인계 파일럿 1건
4주차~저위험 작업부터 승인 생략, 인계 상한·모니터링 정착제한적 완전 자동 체인 + 비용 레버 계측
+
+ + +
+

04설계 원칙 — 두 레이어를 관통하는 것

+

레이어 A와 B는 다른 문제를 풀지만 같은 원리 위에 서 있다. 이 원리들이 AI Scientist 설계의 뼈대다.

+
+
1하나만 읽어도 착수

작업 맥락을 대화가 아니라 정형화된 산출물로 넘긴다. A는 결과 파일, B는 JIRA Handoff 코멘트. 세션이 끊겨도 이어진다.

+
2사람 게이트를 남긴다

되돌리기 어렵거나 외부로 나가는 지점에는 사람이 선다. 승인 게이트는 성숙도에 따라 옮긴다. 처음엔 촘촘하게, 검증되면 넓게.

+
3검증 게이트

커밋·공개 전에 숫자를 다시 계산해 대조한다. weak는 zero가 아니다. 통계가 뒷받침하지 않는 우월·재현 주장을 금지한다.

+
4폭주·비용을 구조로

사람의 주의가 아니라 구조로 막는다. Hop Count 상한, DLQ, 동시성 제한, 모델 티어링, 캐싱, 우선순위 큐.

+
5최소 권한과 격리

AI별 서비스 계정 분리, 프로젝트 단위 권한, main 직접 push 금지. 자동 승인 옵션은 격리 환경 전제. 토큰은 시크릿으로만.

+
6표준 포맷과 재사용

멤버·라우터를 특정 프로젝트에 묶지 않는다. 재사용 스캐폴드(CC BY 4.0), OpenClaw/Codex 네이티브 포맷, MCP 표준.

+
7근거와 코드 분리

method 선택의 근거(paper_analysis/)와 그 근거로 돌리는 코드(pipeline/)를 두 폴더로 나눈다. 판단이 바뀌면 근거만, 실행이 바뀌면 코드만 고친다.

+
+
+ + +
+

05컴포넌트 맵 — 설계 요소가 저장소 어디에 있나

+

이 폴더는 설계를 설명하고, 아래 파일들이 그 설계를 구현한다.

+ +

레이어 A 단일 랩 자동화

+
+ + + + + + + + + + +
설계 요소저장소 위치
랩 구조 지도docs/HARNESS.md
라우팅표 + 산출물 계약CLAUDE.md (Agent routing & artifact contract)
멤버 정의.claude/agents/*.md
오케스트레이터 (실행 입구).claude/skills/paper-production-orchestrator/SKILL.md
단일 컨텍스트 (thesis·claim 등급표)pipeline/hspc-velocity-benchmark/manuscript/PAPER_DIRECTION.md
분석 실행 엔진 (P0–P5)pipeline/hspc-velocity-benchmark/scripts/
method 선택 근거DESIGN.md, paper_analysis/ (dual-lens 14편)
검증 게이트 스크립트scripts/p3_concordance.py, p3_crossdataset_concordance.py, p3_scrambled_null.py
글쓰기 규율 (한국어 윤문).claude/rules/writing-style.md
+ +

레이어 B 멀티 AI 협업 인계

+
+ + + + + + +
설계 요소저장소 위치
인계 아키텍처 (4계층·설치 가이드)guide/ai-handoff-architecture-guide.md
OpenClaw 실현 (허브+워커·큐·비용)guide/openclaw-claude-guide.md
분석 하네스 project frameAGENTS.md (dataset 라우팅을 skills/ROUTES.md에 위임)
MCP 공통 설정.mcp.json (설계 목표는 agent-config 저장소)
팀·역할·AI 계정 매핑Project-Info.md
+
정확성 주의: AGENTS.md가 위임하는 skills/ROUTES.md·openai.yaml 스킬 트리는 이 브랜치 체크아웃에는 없다. 포맷만 규정되어 있고, 실제 스킬 트리는 OpenClaw로 돌릴 때 채운다.
+ +

두 레이어의 접점

+
+ + + + + + +
공유 요소레이어 A에서레이어 B에서
인계 계약결과 파일 (results/FINDINGS.md)JIRA Handoff 코멘트
사람 게이트공개·main 병합 승인초기 Slack 승인
폭주·비용 방지검증 게이트, claim 등급Hop Count 상한, 큐·DLQ, 모델 티어링
실행 도구Claude Code (agent·Skill)OpenClaw 세션 또는 run_agent.sh
라우터 포맷CLAUDE.md 라우팅표Next Agent 필드 → 브리지 분기
+
+ +
+ 생성 문서 · ai_scientist/output_v01/index.html — ai_scientist/의 마크다운 6편(README, 01–05)을 mermaid·HTML로 시각화.
+ 원문 근거: docs/HARNESS.md, .claude/skills/paper-production-orchestrator/SKILL.md, guide/ai-handoff-architecture-guide.md, guide/openclaw-claude-guide.md. +
+ +
+
+
+ + + +