pedrohcgs/claude-code-my-workflow · 上手攻略

  • 仓库：pedrohcgs/claude-code-my-workflow
  • 链接：https://github.com/pedrohcgs/claude-code-my-workflow
  • 分类：skill
  • 作者：Tom
  • 更新：2026-08-25

这是什么

一个开箱即 fork 的 Claude Code 学术工作流模板，把 PhD 课程生产环境里打磨出来的 AI 辅助学术工作流打包成可复用的模板仓库。覆盖论文（LaTeX/Quarto）、幻灯片（Beamer）、数据分析（R/Python）、文献综述、Replication Package 全流程。本质是一个"AI 包工头"——你描述目标，Claude Code 规划路径、调动专项 Agent、修 Bug、核验质量、交付成果。来源是一个真实在跑的生产级 PhD 课程，并持续由社区扩展。

解决什么问题

  • 学术研究者缺乏可靠的 AI 辅助工作流集成方案：Claude Code 虽然强大，但每次新建项目都要从头配置 Rules、Skills、Agent 协作模式
  • LaTeX/Beamer + R 的组合在学术工作流里高度专业化，通用提示词无法针对性处理这类项目的编译、图表联动、引用管理
  • 缺乏系统性的质量门控，AI 产出靠"看起来对"而非真实验证
  • 多人协作（导师/合作者/审稿人）缺少标准化交接规范

快速安装

最小依赖

必须： - Claude Code（安装指南） - git

可选（运行完整 HelloWorld 演示）： - XeLaTeX（Beamer 幻灯片编译） - Quarto（Quarto 演示） - R（数据分析示例） - GitHub CLI - Python 3（运行 ./scripts/backtest.sh 质量门控套件）

最快上手路径

# 1. 在 GitHub 页面上点击 Fork，然后 clone 你的 fork
git clone https://github.com/YOUR_USERNAME/claude-code-my-workflow.git my-project
cd my-project

# 2. 检查环境缺少什么
./scripts/validate-setup.sh
# 报告会列出缺失工具及安装链接

# 3. 启动 Claude Code（VS Code 用户直接开 Claude Code 面板）
claude

# 4. 粘贴起始提示词（替换项目名和描述）
# I am starting to work on [PROJECT NAME] in this repo. [Describe your project in 2–3 sentences.]
# I've set up the Claude Code academic workflow... Please read the configuration files
# and adapt them for my project. Enter plan mode and start.

# 5. 验证环境能跑 HelloWorld
/compile-latex HelloWorld   # 编译 Slides/HelloWorld.tex → PDF
/deploy HelloWorld         # 渲染 Quarto/HelloWorld.qmd → HTML

权限模式说明

  • auto 模式（Pro/Max/Team 新会话默认）：大部分操作自动执行，高风险操作才提示
  • acceptEdits 模式：减少提示频率，切换方式为快捷键绑定或 claude --permission-mode acceptEdits
  • Bypass 模式：完全自主运行，适合信任仓库的全自动执行

模板默认 defaultMode: bypassPermissions（宽放权限），如需收紧改为 defaultMode: "default" 并逐条审批。

核心用法

核心文件结构

├── .claude/
│   ├── settings.json      # Agent 行为配置（defaultMode / hooks / skills）
│   ├── hooks/             # 质量门控钩子
│   └── rules/            # 领域规则（meta-governance.md 等）
├── data-analysis/         # 数据分析模板
├── review-paper/          # 论文模板
├── lit-review/            # 文献综述模板
├── review-r/              # R 代码评审模板
├── scripts/
│   ├── backtest.sh        # 10 项质量门控检查
│   ├── validate-setup.sh  # 环境检查
│   └── install-hooks.sh  # 安装 git 预提交钩子
├── Slides/                # Beamer 幻灯片
├── Quarto/                # Quarto 文档
└── MEMORY.md             # 跨会话学习记录（提交到 git）

质量门控套件（10 项自动检查）

./scripts/backtest.sh

运行 ./scripts/backtest.sh 触发 10 项质量门控： 1. surface-sync：README/文档与代码一致性 2. skill integrity：Skill 规范符合性 3. model currency：模型版本与 SSoT（Single Source of Truth）对齐 4. link and anchor resolution：内外链可访问性 5. Agent Skills spec conformance：Anthropic Agent Skills 规范符合 6. staleness：源码 vs 已发布内容的版本分歧检测 7. repo hygiene：仓库清洁度（废弃文件/临时文件/敏感信息） 8. derived counts：可枚举声明从磁盘重新计数验证 9. ledger coverage：资格台账与实际检查项双向一致 10. seeded hook battery：每条 active guard hook 重新对目标失败案例执行，并发 clean 对照

安装为 git pre-commit 钩子（每次 commit 自动运行 + 质量分 ≥80 门槛）：

./scripts/install-hooks.sh

关键内置 Skills

  • /compile-latex <name> — 编译 Beamer/LaTeX 为 PDF
  • /deploy <name> — 渲染 Quarto 为 HTML
  • MEMORY.md — 记录通用 [LEARN] 条目，在所有 fork 者间共享

Agent 协作模式

不是单次对话，而是多轮规划 → 实施 → 评审 → 修复循环：

  1. 用户描述目标（starter prompt）
  2. Claude 读取配置文件，适应项目上下文
  3. 进入 plan 模式，规划实施路径
  4. 用户批准计划，调用专项 skill
  5. Skill 在其范围内执行 review + verify 循环
  6. 如有问题 Specialist Agent 修 Bug，再核验，再修复

Session 2+ 记忆机制

  • MEMORY.md（提交到 git）：所有 fork 者共享的通用 [LEARN] 条目
  • ~/.claude/projects/<project>/memory/（机器本地，不提交）：机器特定笔记

典型适用场景

  • 硕博论文写作：LaTeX 全流程，Beamer 答辩幻灯片，R 数据分析联动
  • 文献综述自动化：结构化文献检索、分析、引用管理
  • Replication Package 构建：从数据到代码到报告的完整可复现包
  • 课程/教学材料生产：批量生成幻灯片、作业、参考答案
  • 跨学科合作：统一的工作流模板减少协作摩擦

坑与注意

⚠️ Bypass 模式权限过宽：模板默认 bypassPermissions 含 7 条通配规则（Bash(*)、Edit(**)、Write(**) 等），在公开仓库上使用存在安全风险。建议 fork 后立即收窄权限。

⚠️ XeLaTeX / Quarto 首次安装耗时长：validate-setup.sh 会报告缺失项，但实际安装 XeLaTeX 可能需要 30 分钟以上（Mac 用 MacTeX ≈ 4GB）。

⚠️ HelloWorld 演示不要保留：确认环境正常后，删除 Slides/HelloWorld.tex 和 Quarto/HelloWorld.qmd，换上真实内容——演示文件会被意外提交。

⚠️ Python 质量门控套件依赖：backtest.sh 依赖 Python 3 环境，部分检查器（如 ledger coverage）需要额外 Python 包，macOS 默认 Python 可能缺包。

⚠️ git-guardrails hook 不覆盖解释器内写文件：shell 脚本内的写操作、别名展开后执行的写操作，hook 无法检测。

⚠️ 不需 LaTeX/Quarto 时不要跳过：agents、rules、skills、orchestration 模式对任何文本/代码项目都适用，不需要这两个工具时可跳过 HelloWorld 直接进入业务目录。

与同类对比

本仓库 rawzilla/Claude-Sidekick anthropics/skills
定位 学术全流程模板 单会话辅助 通用 Agent Skills
质量门控 10 项自动门控 + git hook 无 无
学术专项 LaTeX/Beamer/R/Replication 无 无
多人协作 git MEMORY.md 跨会话 无 无
复杂度 中高（需配置） 低 中

本仓库的核心差异是系统性的质量门控（backtest.sh 10 项检查）——大多数 Claude Code 模板只给规则不给验证，而这里每一轮交付都经过可枚举的质量关卡。

一句话推荐结论

如果你用 Claude Code 写学术论文、做数据分析或准备会议幻灯片，fork 这个仓库并运行 ./scripts/validate-setup.sh，前 10 分钟的设置可以为你接下来每一个项目省掉 80% 的"Claude Code 配置"内耗——前提是你愿意花半小时把质量门控体系理解清楚再用。