한눈에

Contextual Omics Reasoning and Translational EXploration. 연구실의 유전체·멀티오믹스 데이터분석 코사이언티스트다. 코드를 대신 쓰는 도구가 아니라 가설을 함께 세우고, 연구실 자체 R 패키지·큐레이션 DB·문헌/타깃 지식을 엮어 재현 가능한 분석을 설계·실행·해석한다.

서비스가 아니라 하네스다

다른 앱과 달리 CORTEX 에는 백엔드·워커·정적 화면이 없다. 실행은 이것뿐이다.

cd /data/agents/coscientist/CORTEX
claude          # CLAUDE.md 와 .claude/ 가 이 폴더에서 로드된다

Codex 에서는 AGENTS.md 가 같은 규약으로 연결한다. 단 .claude/hooks/ 는 Claude Code 전용이라 Codex 에서 가드 훅이 자동으로 돈다고 가정하지 않는다(AGENTS.md 에 명시).

그래서 "CORTEX 가 떠 있는가"를 볼 헬스체크 주소가 없다. 운영 점검은 아래 "운영 점검" 절의 스크립트로 한다.

저장소 배치

CLAUDE.md                 역할·원칙·환경·패키지/DB 지도·산출물 규칙 (정본)
AGENTS.md                 Codex 진입점
README.md                 구성·경로·프로젝트 폴더 구조
WORKLOG.md                CORTEX 자산 변경 기록
config/config.md          디렉토리 설정 단일 소스 (편집 대상)
config/config.sh          config.md 파서·로더 (편집 금지)
config/credentials.local.env  로컬 자격증명 (git 제외, 0600)
workbench -> /data/workbench  편의 심링크 (git 제외)
.claude/settings.json     훅 배선 + life-sciences 플러그인 (project 스코프)
.claude/skills/           분석·시스템 스킬 51종
.claude/agents/           서브에이전트 8종
.claude/commands/         /new-project · /session-info · /promote-assets
.claude/hooks/            읽기전용 가드 · 세션 버스 · workflow 동기화 알림
.claude/bus/              세션 간 버스 실행파일 (데이터는 /data/workbench/_bus/)
.claude/tools/            파이썬 도구 — 런타임·격주 업데이트·정합성 점검
.claude/maintenance/      격주 업데이트 예약(schedule.json)·프롬프트
.claude/knowledge/        워크벤치 학습 지식 인덱스(INDEX.md)
.claude/promoted-assets.tsv  워크벤치 자산 승격 원장

.claude/.maintenance/(실행 상태·백업·보고서)와 .claude/settings.local.json(권한 허용목록)은 머신 로컬이라 git 에서 빠진다.

구성요소

• 스킬 — 단계별 벌크 파이프라인(omics-import → omics-qc → omics-preprocess → omics-make-objects → omics-clustering → omics-deg → omics-enrichment, 오케스트레이터 multi-stage-analysis), 체세포 DNA(somatic-*), 메틸화 (cfdna-wgbs-methylation), 단일세포(sc-typing·cell-typing·sc-malignant-typing 등), 공간전사체(spatial-*·rctd-cell-typing), 공통 규약(analysis-scripting· project-data-layout·code-commenting·result-verification), 시스템 스킬 (system-update·system-optimization·asset-promotion·workbench-update), 계산 연계 (slurm-compute·local-qwen).
• 서브에이전트 — analysis-guide · analysis-planner · biostat-reviewer · literature-interpreter · pipeline-tracer · report-writer · repro-auditor · result-interpreter.
• 외부 지식 소스 — anthropics/life-sciences 마켓플레이스의 커넥터별 플러그인을 project 스코프로 켠다(.claude/settings.json 의 enabledPlugins). PubMed·Open Targets·Consensus 는 인증 없이 붙고, ChEMBL·ClinicalTrials·bioRxiv·Synapse·Wiley 는 대화형 세션에서 /mcp OAuth 가 필요하다. 10x Genomics 는 플러그인이 아니라 user 스코프 stdio 서버로 붙이게 돼 있고 CLAUDE.md 기준 토큰 미등록 — 미가동이다.

경로와 쓰기 권한

모든 루트는 config/config.md 의 설정 블록(cortex-config:begin ~ end)에만 적는다. 문서·스킬은 자리표시자(<DATA_ROOT> 등)를 쓰고, 훅·커맨드는 config/config.sh 를 source 해서 값을 받는다. 로더는 파일이 없거나 파싱에 실패하면 기본값으로 fail open 한다.

설정 블록에는 이 밖에 Slurm 파티션(SLURM_CPU_PARTITION=cpu·SLURM_GPU_PARTITION=gpu), MUSE 관측 주소(MUSE_AGENT_URL), ContextBio 소스 루트(SYSTEM_SOURCE_ROOT=/data/agents/ContextBio), 공유 Qwen helper(QWEN_HELPER — AURORA 저장소의 exec/qwen_slurm.py), NCBI 연락처·키 항목이 있다. NCBI API 키 값은 config.md 에 두지 않는다 — git 제외 파일 config/credentials.local.env (0600)에 두고, AGENTS.md 도 config 전체를 출력하지 말라고 적어 둔다.

가드는 deny-list 다

.claude/settings.json 이 PreToolUse 에 guard-readonly.sh(Write·Edit 류)와 guard-readonly-bash.sh(Bash)를 건다. 막는 것은 <DATA_ROOT>·<RAWDATA>·홈 산출물 쓰기뿐이고, 읽기 소스로 쓰는 것은 막지 않는다. /data ↔ /mnt/S1/… 별칭은 realpath 로 해소한다 — <RAWDATA> 는 realpath 가 /mnt/S1/data/rawdata 로 다른 루트 (/mnt/S1/sdata/…)와 부모가 다르다.

가드가 허용해도 파일시스템이 거부할 수 있다. <PROCESSED_DATA> 최상위는 그룹 쓰기가 없어 새 프로젝트 폴더를 만들 수 없고, 그 아래 HCC_multiome 은 소유자 외 읽기전용이다.

그 밖의 훅 — PostToolUse 의 workflow-sync-reminder.sh, 세션 버스 bus-deliver.sh (UserPromptSubmit)·bus-status.sh(SessionStart). 버스 훅 둘은 fail-open 이다.

ContextBio 앱과의 연결

CORTEX 는 사이트 앱을 부르지 않는다. 연결점은 파일과 공유 구현이다.

• AURORA → CORTEX 인계. AURORA 의 R/06_handoff.R 이 상류 산출물 폴더에 cortex_handoff.json 매니페스트를 쓴다. CORTEX 의 omics-import·somatic-* 는 <PROCESSED_DATA>/<project>/AURORA/ 에서 이 매니페스트부터 읽는다(2026-08-14 이전 산출물은 AURORA-Seq/). BAM·VCF 는 복사하지 않고 매니페스트의 절대경로로 제자리에서 읽는다. AURORA 쪽은 AURORA 구현.
• Qwen helper 공유. local-qwen 스킬은 사본을 두지 않고 ContextBio 의 공유 helper 를 부른다(QWEN_HELPER·QWEN_RUNTIME).
• Slurm. 전처리·학습·상당한 평가는 MUSE Slurm(c1 controller, cpu/gpu 파티션)으로 제출한다. 2026-09-17 사용자 지시로 AURORA/PepDesigner 의 새 계산에도 같은 원칙이 적용되며, 앱 운영 정본은 사이트 저장소의 SLURM_POLICY.md 다 (운영 소스·실행 관리).

사이트와의 관계 — 준비중 카드

사이트에는 앱 페이지가 없다. 지금 상태는 셋이 맞물려 있다.

1. content.py — PLACARD_APPS = ("cortex", "muse"). 앱 페이지 없이 제품 목록에만 실리는 앱이다. load_info() 가 SITE_APPS + PLACARD_APPS 에 든 제품만 남긴다.
2. info.md — key: cortex 카드(group: agent, url: "/cortex")의 service_url 이 비어 있다. 비어 있으면 단추가 "준비중" 으로 비활성 표시된다. 주석대로 전용 도메인이 준비되면 이 값을 채운다.
3. firebase.json — /cortex{,/**} → /home 302 리다이렉트. 호스팅 target 마다 같은 규칙이 들어 있다. 카드 주소를 직접 쳐도 홈으로 돌아간다.

tools/check_release.py 의 비활성 목록(inactive)에 cortex 는 없다 — PLACARD_APPS 라 이름 노출이 정상으로 취급되므로 공개 쪽이나 이 위키에 "cortex" 가 보여도 배포가 서지 않는다. 2026-09-19 에는 cortex 가 비활성으로 분류돼 있어 위키 한 단어 때문에 dev 배포가 조용히 실패한 적이 있다. 검사 규칙을 바꿀 때는 public/ 을 지우고 새로 빌드한 뒤 tools/check_release.py 로 확인한다.

격주 업데이트 cron

workbench-update 스킬은 워크벤치·서비스 소스의 변경을 14일마다 학습해 CORTEX 문서·스킬· 보조 도구에 반영한다(2026-09-13 사용자 지속 승인. 원본 데이터·패키지·운영 서비스 변경은 승인 범위 밖).

• 예약 — .claude/maintenance/schedule.json: first_run 2026-09-27 09:00 KST, interval_days 14, timeout_seconds 3600, 실행기 codex 바이너리.
• 진입점 — .claude/tools/biweekly_update.py. 매일 09:00 에 불려 due 일 때만 돈다. 잠금 파일로 동시 실행을 막는다.
• cron 설치 — .claude/tools/install_maintenance_cron.py(인자 없으면 항목만 출력, --install 로 반영). 호스트 시간대가 Asia/Seoul 이 아니면 설치를 거부한다.
• cron 은 c3 에 있다. c1·g1·g2 의 crontab 에는 없다(2026-09-29 확인). 로그는 .claude/.maintenance/cron.log, 회차별 기록은 .claude/.maintenance/<YYYYMMDD-HHMMSS>/.

운영 점검

cd /data/agents/coscientist/CORTEX
python3 .claude/tools/biweekly_update.py --check   # 예약·due·마지막 성공/실패
python3 .claude/tools/check_cortex.py              # 도구 구문·config 키·스킬 참조 정합성 (작업 실행 없음)
python3 .claude/tools/test_runtime.py              # 회귀 테스트 (임시 파일만, 잡·cron·모델 호출 없음)
python3 .claude/tools/cortex_runtime.py status     # Slurm 큐·MUSE 상태
python3 .claude/tools/cortex_runtime.py qwen --check   # Qwen helper 경로 확인 (--probe 는 후보 점검)
claude mcp list                                    # 커넥터별 연결·인증 상태

cortex_runtime.py submit --test-only 는 제출 전 검사다. qwen --probe 가 통과해도 추론 성공을 뜻하지 않는다.

2026-09-29 현재 격주 업데이트는 성공한 적이 없다. --check 의 last_success 가 null 이고, 09-27·09-28·09-29 회차가 모두 codex exec failed: 1 로 끝났다. 그날 회차의 executor.log 원인은 Codex 로그인 토큰 폐기(refresh token revoked → 401)다. c3 에서 cron 을 도는 계정으로 Codex 에 다시 로그인해야 풀린다. 매일 due 상태로 재시도하므로 로그가 계속 쌓인다.

주의할 점

• CORTEX 자산 업데이트 권한은 사용자에게만 있다. 지속 승인(격주 업데이트)·자산 승격 게이트(G1~G8 전부 통과, /promote-assets 명시 요청 시에만) 밖의 변경은 제안하고 멈춘다. 반영 뒤에는 정합성 검토와 WORKLOG.md 기록이 필수다.
• 원본 <DATA_ROOT> 는 제자리에서 고치지 않는다. 패키지 개선은 <PKG_DEV> 사본에서 R CMD check 로 검증해 패치+리포트로 낸다. 가드는 안전망이고 최종 책임은 이 원칙이다.
• 비밀값을 문서·설정 블록에 적지 않는다. NCBI 키는 credentials.local.env, 10x 토큰은 user 스코프 ~/.claude.json 에 둔다(그룹이 읽는 프로젝트 settings.json 에 두지 않는 이유).