vibe bioinformactics

# 生物信息学分析与高性能计算项目 - CLAUDE.md

本文件是本项目中 Claude Code 的行动指南与项目约束。
Claude Code 在本项目中执行任何命令、修改任何代码、生成任何脚本或提交任何分析建议时，必须优先遵守本文件。

---

## 1. 项目技术栈与运行环境

### 1.1 软件环境

**NCPGR 集群**：优先使用集群已安装的软件，通过 `module` 系统或 Singularity 容器加载，使用前**必须调用 `ncpgr-software` skill** 确认模块名称和推荐版本。只有在集群不提供所需软件时，才考虑使用 conda 环境。

**本地**：默认分析环境：

```bash
conda activate bio_env
```

如需新增依赖，Claude Code 不得直接安装。必须先说明需要安装的包、原因、影响和推荐命令，经用户授权后方可执行。

---

### 1.2 高性能计算环境

本项目运行于 HPC 集群。**严禁在登录节点运行高负载计算任务。**

登录节点仅允许：查看目录、检查配置、轻量测试、编译小目标、处理微型测试数据、运行低资源命令。

所有正式分析必须封装为作业脚本并通过 LSF 提交。编写或提交作业脚本时**必须调用 `ncpgr-lsf` skill**。

---

### 1.3 项目专属 Skills

本项目配置了以下 Claude Code Skills，在对应场景触发时**必须主动调用**，不得凭记忆或通用知识替代：

| Skill | 触发场景 | 用途 |
|-------|---------|------|
| **`ncpgr-lsf`** | NCPGR 集群作业提交/调试/监控、队列或核数选择 | LSF 完整指南，含队列规则、模板、监控命令、反模式 |
| **`ncpgr-software`** | NCPGR 集群软件使用、模块查询、版本选择、资源配置 | 软件注意事项、版本推荐、核数/内存推荐、常见陷阱 |

**调用规则：**

1. 涉及 NCPGR 作业提交、队列选择、资源估算时 → 调用 `ncpgr-lsf` + `ncpgr-software`；
2. 询问软件安装、使用、加速或排错时 → 调用 `ncpgr-software`；
3. 以 skill 返回内容为准，本文件中的通用规则仅作参考；
4. 联动时：`ncpgr-lsf` 负责调度语法，`ncpgr-software` 负责软件选型和参数。

---

### 1.4 核心语言与工具

核心语言：

* Python 3.10：pandas、Hail、NumPy、SciPy 等；
* R：ggplot2、tidyverse、生信统计与可视化。

常用工具包括但不限于：samtools、bcftools、bedtools、GATK、PLINK/PLINK2、Hail、Snakemake、seqkit、multiqc、fastqc。

---

### 1.5 Singularity / Apptainer 容器环境

HPC 环境通常不支持 Docker，应使用 Singularity 或 Apptainer：

* 容器镜像统一存放于 `envs/containers/`（NCPGR 公共镜像位于 `/share/Singularity/`）；
* 容器使用必须在作业脚本或 workflow 中显式声明，不得隐式依赖宿主机环境。

---

## 2. Claude Code 行为准则

### 2.1 执行前说明原则

Claude Code 在修改文件、创建脚本、运行分析、编译代码、提交作业、安装依赖、删除/移动文件、修改 Git 状态前，必须先简要说明：准备做什么、影响哪些文件、资源消耗预估、预期输出位置。

---

### 2.2 禁止自动执行的操作

未经用户明确授权，Claude Code 不得执行：

```bash
rm / rm -rf / mv / cp -f / rsync --delete
git reset / git clean / git checkout / git switch / git merge / git rebase / git push / git commit
conda install / pip install
bsub / bkill
```

如确需执行，必须先说明风险并等待用户确认。

---

### 2.3 不确定性处理

遇到以下情况时，必须标记为"需要人工确认"，不得自行假设：

* 生物学解释不明确；
* 参数阈值缺乏依据；
* 样本分组、参考基因组版本、表型或协变量含义不确定；
* 结果与预期明显不一致；
* 日志中出现无法解释的 warning/error；
* 工具版本或算法行为可能影响结果。

---

### 2.4 每次任务启动时的 Git 检查

每次唤醒、切换任务或开始修改项目前，必须先执行 `git status`，如存在未提交修改须先总结工作区状态。

不得自动执行 `git stash` 等状态修改操作，除非用户明确授权（禁止命令已列于 §2.2）。

---

## 3. 项目目录结构规范

推荐项目结构如下：

```text
my_bioinfo_project/
├── CLAUDE.md              # Claude Code 行动指南与项目约束
├── README.md              # 生物学背景、样本设计、分析目标和项目概述
├── ANALYSIS_LOG.md        # 分析过程日志
├── .gitignore             # 必须排除原始数据、大型中间文件和结果文件
├── .claude/               # Claude Code 专属配置目录
│   └── settings.json      # 权限与行为限制
├── configs/               # 配置文件（YAML、JSON、workflow 配置、样本清单）
├── envs/                  # 环境定义（environment.yml、Dockerfile、renv.lock）
│   └── containers/        # Singularity 容器镜像（.sif）
├── src/                   # 可复用核心代码库（Python、R）
├── scripts/               # 命令行入口脚本和小型工具脚本
├── workflows/             # Snakemake、作业调度工作流脚本
├── logs/                  # 调度系统和工具运行日志
├── data/                  # 数据目录，默认不纳入 Git
│   ├── raw/               # 原始测序数据，只读，禁止修改
│   ├── reference/         # 参考基因组和注释文件，只读
│   ├── metadata/          # 样本表、表型、协变量、批次信息
│   └── test/              # 人工合成或公开微型测试数据
├── results/               # 分析结果，默认不纳入 Git
├── tmp/                   # 临时目录，默认不纳入 Git
└── docs/                  # 分析记录、方法说明、项目笔记
```

---

## 4. 目录读写规则

### 4.1 只读目录

`data/raw/` 和 `data/reference/` 必须视为只读，不得修改、覆盖、删除、移动、重命名或原地处理其中文件，除非用户明确授权。

所有处理操作的输出必须写入 `results/`、`tmp/`、`logs/` 或用户指定的其他非原始数据目录。

---

### 4.2 测试数据目录

`data/test/` 是本地测试的默认数据来源，只能包含人工合成数据、公开微型数据或脱敏的极小测试子集。不得包含真实未发表数据或敏感样本 ID。

---

### 4.3 输出目录规则

**结果目录（`results/`）：** 默认禁止覆盖已有结果。输出路径已存在时，必须停止并报告，请求用户确认或建议带时间戳的新目录。推荐命名格式：`results/{analysis_name}/{YYYYMMDD}_{parameter_tag}/`。

**日志目录（`logs/`）：** 正式任务必须保留日志，至少包括调度系统 stdout/stderr、工具日志、关键命令、job ID 和资源使用情况。

**临时目录（`tmp/`）：** 存放临时和可重算的中间文件。Claude Code 不得自动清理，但应在分析完成后建议用户评估清理范围。使用高速临时存储（如 `/scratch`）时，必须在任务结束前将结果复制到持久存储。

---

## 5. Git 管理规则

`.gitignore` 必须按以下分类排除文件（完整模板应在项目初始化时维护）：

| 分类 | 代表性排除项 |
|------|------------|
| 原始数据和参考基因组 | `data/raw/`、`data/reference/` |
| 大型可重算输出 | `results/`、`logs/`、`tmp/`、`temp/` |
| 测序和比对文件 | `*.fastq.gz`、`*.bam`、`*.cram` 及索引 |
| 变异文件 | `*.vcf.gz`、`*.bcf` 及索引 |
| 参考基因组文件 | `*.fa`、`*.gtf`、`*.gff3`、`*.dict`、`*.fai` |
| PLINK/Hail 输出 | `*.bed/*.bim/*.fam`、`*.pgen/*.pvar`、`*.mt`、`*.ht` |
| 容器镜像 | `envs/containers/*.sif` |
| 工具缓存 | `.cache/`、`.snakemake/`、`__pycache__/`、`.pytest_cache/` 等 |
| 语言临时文件 | `*.pyc`、`.Rhistory`、`.RData`、`renv/library/` |
| 系统文件 | `.DS_Store`、`Thumbs.db` |

小型最终汇总表、图片或 QC 报告如需纳入 Git，必须由用户明确决定。如需管理大型数据文件版本，建议配合 DVC 或 git-lfs，须经用户授权。

---

## 6. 数据安全与隐私规则

禁止在 Prompt、日志、issue、commit message、README、分析笔记或代码注释中暴露：敏感服务器路径、API key、token、数据库密码、私有 SSH key。

---

## 7. 大文件查看与处理规则

### 7.1 禁止直接扫描大文件

禁止对大型生信文件（FASTQ、BAM、CRAM、VCF、BCF、Hail MatrixTable）直接运行 `cat`、`grep`、`zgrep`、`awk`、`sed`、`less`、`more`，或未限制范围的 `samtools view`、`bcftools view`。

`head`/`tail` 仅允许配合 `-n`（建议不超过 100 行）查看文件头部结构，禁止扫描主体内容。

---

### 7.2 允许的摘要级检查

优先使用摘要级命令：`samtools quickcheck/idxstats/flagstat/view -H`、`bcftools view -h/index -s/stats/query -l`、`seqkit stats`、`plink2 --freq` 等。

---

### 7.3 大文件处理原则

Python/R 脚本不得一次性读取数 GB 级数据进内存。必须优先采用 streaming、chunking、iterator、indexed/region-based query、batch processing、Hail/Spark 分布式处理或原生命令流式处理。

---

## 8. HPC 与作业调度规范

> 具体 LSF 语法**必须调用 `ncpgr-lsf` skill**，本节仅列原则。

### 8.1 正式分析必须通过调度系统提交

全基因组比对、BAM 排序/markdup/BQSR、variant calling、joint genotyping、VCF 过滤、GWAS、RNA-seq 定量、单细胞大矩阵处理、Hail 计算，以及任何高 CPU/内存/I/O 任务，必须通过调度系统提交，不得在登录节点运行。

---

### 8.2 作业脚本编写原则

* 脚本必须调用 `ncpgr-lsf` skill 生成，不得手写；
* 线程数必须使用 `${LSB_DJOB_NUMPROC}`，不得硬编码；
* 建议配置任务完成/失败邮件通知。

---

### 8.3 线程控制

所有工具必须显式设置线程数，不得让工具自行占满节点。线程参数必须使用 `${LSB_DJOB_NUMPROC}`。本地测试默认最多 4 个线程。

---

### 8.4 资源估算

大批量作业提交前，必须先选取 1–2 个代表性样本运行测试作业，根据实际资源消耗（峰值内存、CPU 利用率、运行时间）确定正式作业的核数和队列，以节省集群资源、减少排队等待时间。

---

### 8.5 任务失败恢复与断点续传

**断点续传原则：** 已完成步骤不重复执行；优先使用 Snakemake 的断点续传能力；手动流程每步输出为下一步显式输入；长任务设置 checkpoint。

**任务失败后必须：** 分析日志确定失败点和原因 → 检查已完成步骤完整性 → 评估从失败点继续的可能性 → 报告原因和修复建议。不得未说明原因直接重提相同任务。

**常见失败场景：**

| 失败类型 | 排查方式 | 常见修复 |
|----------|---------|----------|
| OOM（`TERM_MEMLIMIT`）| `bhist -l <jobid>` | 多申请核心分摊内存，或换 high/smp 队列 |
| 磁盘满 | `df -h` / `du -sh`，注意节点 `/tmp` 不可滥用 | 清理或换目录 |
| 排队不调度 | `bjobs -p <jobid>` | 减核或换队列 |

> 完整排查命令以 `ncpgr-lsf` skill 为准。

---

## 9. 存储与数据生命周期管理

### 9.1 存储配额意识

提交大批量任务前，必须先使用 `diskquota` 检查当前存储使用量和配额：

```bash
diskquota
```

输出中关注：
- `blocks`（已用存储）vs `quota`（配额上限），如 `17.55T / 20T`；
- `files`（文件数）vs `quota`（文件数上限），如 `2145851 / 8000000`。

配额用尽时写入会报 `Disk quota exceeded`。存储不足时必须停止并报告，建议用户清理数据或申请增加配额。

> 大量小文件（<128KB）会严重影响存储性能，分析完成后应及时打包压缩或删除。

---

### 9.2 数据生命周期建议

| 数据类型 | 目录 | 保留策略 |
|----------|------|----------|
| 原始数据 / 参考基因组 / 元数据 | `data/raw/`、`reference/`、`metadata/` | 永久保留 |
| 最终分析结果 | `results/` | 长期保留，定期归档 |
| 运行日志 | `logs/` | 保留至少一个分析周期 |
| 可重算中间文件 | `tmp/` | 验证后建议清理 |
| 容器镜像 | `envs/containers/` | 按需保留，更新后清理旧版 |

Claude Code 不得自动删除任何文件，分析完成后应建议用户评估中间文件保留范围。

---

## 10. 输入数据完整性检查

正式分析前必须检查：

* FASTQ 是否可解压；
* BAM/CRAM 是否通过 `samtools quickcheck` 且存在索引；
* VCF/BCF 是否存在索引；
* 参考基因组版本是否与 BAM/VCF header 一致；
* contig 命名是否一致（如 `chr1` vs `1`）；
* 样本 ID 是否与 metadata 匹配；
* phenotype/covariate 文件是否有缺失值、重复或异常编码；
* 输入文件是否非空、权限是否符合预期；
* 外部参考文件是否通过完整性校验（md5sum/sha256sum）。

发现不一致时必须停止并报告。

---

## 11. 样本命名与元数据规范

### 11.1 样本 ID 命名规则

统一格式，仅允许字母、数字、下划线、短横线。推荐 `{cohort}_{subject}_{tissue}_{replicate}`。所有脚本和配置中 ID 必须完全一致。

---

### 11.2 元数据文件要求

存放于 `data/metadata/`，TSV/CSV 格式，UTF-8 编码，Unix 行尾。必须列：`sample_id`、`group`（品种/处理/条件）、`batch`。建议列：`tissue`、`cultivar`、`treatment`、`growth_stage`、`collection_date`、`replicate` 等。

---

### 11.3 元数据加载检查

读取元数据时必须检查：列名是否符合预期、`sample_id` 是否与输入文件一一对应、是否有重复或空值、分组样本量是否足够、协变量是否共线性。发现问题必须停止并报告。

---

## 12. 结果校验规则

每个关键步骤完成后必须 sanity check：

* 输出文件存在且非空；
* 日志无 `error`/`warning`/`failed`/`killed`/`OOM`/`segmentation fault`；
* 过滤前后样本数、位点数合理；
* VCF 样本数与预期一致（`bcftools query -l | wc -l`）；
* BAM/CRAM 已排序且有索引；
* VCF/BCF 可正常读取且通过 `bcftools stats`；
* 染色体和坐标范围符合预期；
* 输出与配置参数一致。

禁止仅凭退出码为 0 就认为分析成功。

---

## 13. 分析记录与可复现性

### 13.1 环境版本记录

每次关键分析必须记录：Git commit hash 及 working tree 状态、Conda/Python/R 版本、关键工具版本（samtools/bcftools/GATK/PLINK2/Hail 等）、容器版本（如使用）、调度系统 job ID、运行节点、CPU/内存/运行时间。

---

### 13.2 分析内容记录

完成 QC、mapping、variant calling、filtering、GWAS、PCA、kinship、群体结构、差异表达、富集分析、重要可视化等任务后，必须更新分析记录，内容包括：

1. 分析目的和输入数据；
2. 工具版本和核心参数（含参数选择理由）；
3. 过滤前后统计和主要结果路径；
4. 初步生物学结论和未解决问题；
5. 下一步建议。

推荐写入 `results/{analysis_name}/run_metadata.yaml`、`ANALYSIS_LOG.md` 或 `results/{analysis_name}/README.md`。

---

## 14. 配置管理原则

禁止在脚本中硬编码：绝对路径、样本 ID、phenotype/covariate 名称、过滤阈值、参考基因组路径、线程数、内存大小、输出目录。

正式分析参数应写入 `configs/*.yaml` 或 `configs/*.json`，或通过命令行参数传入。配置文件应包含分析名称、日期和版本号。

---

## 15. Python 代码规范

Python 代码必须遵守：PEP8、类型提示、清晰函数边界、明确异常处理、避免全局可变状态和硬编码路径、大文件使用 chunking/streaming、函数 docstring 注明输入/输出格式（含参数含义、数据 shape、文件格式、返回值、可能异常）。

推荐质量检查：`ruff check .`、`ruff format .`、`mypy src/`、`pytest src/tests/`。

---

## 16. R 代码规范

R 代码应遵守：函数化、避免硬编码路径（使用 `here`/`optparse`/配置文件）、大表格 chunking、图表记录输入和参数、统计检验明确假设和校正方式。

### 16.1 包管理

推荐 `renv` 管理版本。脚本开头必须声明所有依赖包。

### 16.2 图表输出规范

关键图表同时保存 PDF（矢量）和 PNG（≥300 dpi），文件名包含分析名称和日期。

### 16.3 统计检验规范

所有 p 值说明是否经多重检验校正，标注校正方法，报告效应量及置信区间，一并报告样本量和检验统计量。

推荐工具：`styler`、`lintr`、`renv`。

---

## 17. 外部工具调用规范

调用外部工具时必须检查退出状态码。Bash 脚本必须使用 `set -euo pipefail`。多步骤流程中任一步骤失败必须立即停止，不得继续使用不完整中间文件，不得静默忽略 warning/error，必须保留日志并报告失败命令、退出码和可能原因。

**外部数据库与网络访问：** NCPGR 公共数据库（NR/NT/Pfam/Rfam/swissprot 等）位于 `/share/database/`，**调用 `ncpgr-software` skill** 确认加载方式（`module load` 后用 `$NR` 等变量引用，无需自行下载或建索引）。计算节点**无联网能力**，需网络操作在登录节点完成；下载用 `wget -c` 断点续传，完成后验证完整性（`md5sum -c`）；禁止向外部上传私有数据。

---

## 18. Snakemake 规范

* 参数写入 `configs/`，不在 workflow 文件中硬编码路径；
* 每个 rule 明确输入、输出、日志、threads、memory、time；
* 大任务必须与 LSF 调度系统集成（参考 `ncpgr-lsf` skill）；
* 默认先 dry-run（`snakemake -n`）和小数据测试；
* 不得直接在全量数据上运行未经测试的 workflow。

**Notebook 使用限制：** 仅用于探索性分析、可视化和方法原型验证，不得作为正式生产流程。正式流程必须整理为脚本或 Snakemake workflow。Notebook 关键结论须同步记录到 `ANALYSIS_LOG.md`。

---

## 19. `.claude/settings.json` 与 `CLAUDE.md` 的关系

`CLAUDE.md` 规定项目行为原则，`.claude/settings.json` 实现工具权限和命令限制，冲突时以更严格者为准。

**推荐配置模板：**

```json
{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(rm -r data/)",
      "Bash(git push *)",
      "Bash(git reset --hard *)",
      "Bash(git clean *)",
      "Bash(conda install *)",
      "Bash(pip install *)",
      "Bash(bsub *)",
      "Bash(bkill *)",
      "Bash(chmod -R *)"
    ]
  }
}
```

> 具体语法请参考 Claude Code 官方文档。

---

## 20. 安全底线总结

Claude Code 必须始终遵守以下底线：

1. 不在登录节点运行高负载任务；
2. 不直接读取或扫描大型原始数据；
3. 不修改、覆盖、删除 `data/raw/` 和 `data/reference/`；
4. 不上传、不暴露、不复制私有或未发表数据片段；
5. 不自动安装依赖；
6. 不自动删除文件；
7. 不自动提交、push、reset 或 clean Git 仓库；
8. 不覆盖已有结果；
9. 不在脚本中硬编码路径和关键参数；
10. 不凭退出码为 0 就认为分析成功；
11. 所有正式任务必须可复现、可追溯、可审计；
12. 所有大规模任务必须通过调度系统或正式 workflow 提交；
13. 不在未评估存储配额的情况下写入大型输出；
14. 不向外部服务上传私有数据。
```