Agentic workflow for Physics student

很早就想整理一下这套研究笔记的工作流。起因不复杂：一边是越来越庞大的笔记库和文献库，另一边是越来越强的本地 AI Agent——怎么让它们好好配合，而不是互相添乱？

这篇文章记录了一套以文件夹为共享真相源的研究工作流，结合了 Claude Code、Codex、Obsidian、VS Code 和 Zotero。核心思路就一句：把研究文件夹当成一个小型研究操作系统——Obsidian 是思考界面，VS Code 是文件和差异审查界面，Zotero 掌管文献权威，而 Claude Code 和 Codex 作为本地 Agent，在读取同一套规则后，操作同一批文件。

你可以把这篇文章当作搭建自己工作流的模板，替换其中的路径、目录名和研究规则即可。

What each tool does

Tool Role in the workflow Best use
Obsidian Main knowledge base Writing notes, linking concepts, browsing literature notes, keeping research context visible
VS Code Project editor Inspecting files, reviewing diffs, using terminals, editing configs, handling scripts
Zotero Bibliographic source of truth Metadata, PDFs, citation keys, annotations, reference search
Claude Code Recommended first local agent for new users Building the initial workflow in VS Code, reading this Markdown file as a prompt, navigating files, drafting configs
Codex Second local agent and stronger automation partner Multi-file edits, repo inspection, workflow automation, verification, structured note creation
MCP servers Tool bridge Letting agents access Obsidian and Zotero through explicit local interfaces
Git / Obsidian Git Version history Automatic backups and recovery for the vault

For a new user, start with Claude Code in VS Code before adding more automation. This gives the user one familiar window, one file tree, one terminal, and one visible diff. Once the folder works with Claude Code, adding Codex is mostly a matter of reusing the same rules and MCP configuration.

Recommended first path:

  1. Create or choose a research folder.
  2. Open the folder in VS Code.
  3. Open the same folder as an Obsidian vault.
  4. Install and configure Zotero.
  5. Add this Markdown guide to the folder.
  6. Ask Claude Code to read this guide and build the workflow files.
  7. Review every generated file in VS Code before using agents on real notes.
  8. Add Codex after the Claude Code workflow is stable.

提示：Claude Code 可以直接用这篇 Markdown 文件本身作为实现提示词。把这份文件放进新用户的研究文件夹，在 VS Code 中打开该文件夹，然后让 Claude Code 读取它并生成本地工作流文件。

First Claude Code prompt for a new user:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Read `Agentic research workflow.md` as the workflow specification.

Set up this folder as an Obsidian + Zotero + Claude Code research workflow.

Create or update only these files unless I approve more:
- `CLAUDE.md`
- `AGENTS.md`
- `.mcp.json`
- `.claude/settings.local.json`
- `.codex/config.toml`

Do not modify `.obsidian/`.
Do not invent citation metadata.
Use placeholders where my local paths or Zotero executable path are unknown.
After drafting the files, explain what each file does and what I still need to configure manually.

After Claude Code creates the first version, use a second prompt to verify:

1
2
3
Review the workflow files you just created.
Check that the vault path, Zotero MCP command, Obsidian MCP command, citation rules, no-touch folders, and plugin assumptions are consistent.
Do not edit yet. Report problems first.

Only after this passes should a new user ask an agent to write or reorganize real research notes.

Folder layout

A useful setup keeps agent instructions and tool configuration at the root of the research folder:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
research-vault/
  Agentic research workflow.md
  AGENTS.md
  CLAUDE.md
  .mcp.json
  .codex/
    config.toml
  .claude/
    settings.local.json
  .obsidian/
  literature/
  notes/
  projects/
  meetings/
  attachments/
  templates/
  zotero-export/

In this vault, the same pattern appears as:

1
2
3
4
5
6
7
8
9
10
11
12
13
E:\note\
  Agentic research workflow.md
  AGENTS.md
  CLAUDE.md
  .mcp.json
  .codex\config.toml
  .claude\settings.local.json
  .obsidian\
  physics\
  Machine Learning\
  组会\
  todo\
  zoterocite\

提示：把 Agent 指令放在 vault 根目录，不要分散在聊天记录里。新的 Agent 应该能够从读取 AGENTS.md 或 CLAUDE.md 开始，立刻知道自己能读什么、写什么、验证什么。在本 vault 中，从 AGENTS.md 和 CLAUDE.md 开始。

What each setup file is for

When Claude Code builds the workflow from this Markdown file, it should produce a small number of durable setup files. Each one has a separate job.

File or folder Owner Purpose New-user advice
Agentic research workflow.md Human The long onboarding and implementation guide. Keep it readable and share it with new users.
CLAUDE.md Claude Code Local operating rules for Claude Code. This should be short, strict, and specific to the vault.
AGENTS.md Codex and other agents Local operating rules for Codex-style agents. Mirror CLAUDE.md unless there is a reason to differ.
.mcp.json Claude Code MCP server configuration, especially Obsidian and Zotero. Use absolute local paths and placeholders until the user confirms them.
.claude/settings.local.json Claude Code Local permissions for Claude Code. Start read-only or narrow; add write permissions gradually.
.codex/config.toml Codex Codex MCP server configuration. Add after the Claude Code setup is working.
.obsidian/ Obsidian Obsidian app, core plugin, and community plugin settings. Do not ask agents to edit this folder casually. Configure plugins through Obsidian first.
zoterocite/ or zotero-export/ Zotero/Obsidian plugins Exported Zotero metadata used by Obsidian plugins. Treat as generated or read-only unless the export workflow says otherwise.
template/ Human/Obsidian Note templates, including Zotero note templates. Keep templates stable; update them deliberately.

For a new user, Claude Code should not try to perfect everything at once. The first successful setup is one where:

  • CLAUDE.md and AGENTS.md exist.
  • .mcp.json has plausible Obsidian and Zotero entries.
  • The user knows which paths still need manual confirmation.
  • Claude Code can list the vault files.
  • Zotero search works for one known paper.
  • A small test note can be created and reviewed in VS Code and Obsidian.

Plugins and local integrations

This workflow uses three layers of plugins or plugin-like integrations:

  1. Obsidian community plugins, which improve the note-taking interface.
  2. MCP servers, which let Claude Code and Codex talk to local tools.
  3. Codex-side plugins/connectors, which add task-specific agent capabilities.

New users do not need every plugin on day one. The minimum useful stack is Obsidian, VS Code, Claude Code, Zotero, Git, Obsidian MCP, and Zotero MCP. The remaining plugins make the workflow better once the basic loop is stable.

Active Obsidian community plugins in this vault

These plugins are enabled in .obsidian/community-plugins.json. Agents should know what they do, but should not edit .obsidian/ plugin settings unless explicitly asked.

Plugin What it does Role in this workflow
Git 2.35.2 (obsidian-git) Integrates Git version control and automatic backup into Obsidian. Protects the vault from bad agent edits by keeping recoverable history.
BibNotes Formatter 0.9.219 (bibnotes) Imports and formats annotations from Zotero. Builds literature notes and annotation sections from Zotero data.
Zotero Integration 3.2.1 (obsidian-zotero-desktop-connector) Inserts/imports citations, bibliographies, notes, and PDF annotations from Zotero. Connects Obsidian writing to Zotero references and PDFs.
Latex Suite 1.10.4 (obsidian-latex-suite) Adds snippets, text expansion, and editor enhancements for LaTeX math. Makes physics/math notes faster to write and easier for agents to preserve.
Completr 3.2.0 (obsidian-completr) Adds auto-completion for LaTeX, frontmatter, and ordinary writing. Helps with structured note editing and math-heavy writing.
Tasks 7.22.0 (obsidian-tasks-plugin) Tracks tasks across the vault, including due dates, recurring tasks, done dates, and filters. Turns research TODOs into queryable task lists.
Spaced Repetition 1.13.3 (obsidian-spaced-repetition) Reviews flashcards and entire notes over time. Supports long-term memory for formulas, vocabulary, and concepts.
LanguageTool Integration 0.3.7 (obsidian-languagetool-plugin) Adds LanguageTool-based writing checks. Helps polish English prose, abstracts, emails, and paper notes.
Language Learner 0.2.7 (obsidian-language-learner) Supports reading, word lookup, review, use, and statistics for language learning. Useful for TOEFL or academic English practice inside the same vault.

Recommended Obsidian plugin install order for a new user:

  1. Git, so every later change has history.
  2. Zotero Integration, so references and PDF annotations enter the vault correctly.
  3. BibNotes Formatter, if the user wants imported Zotero annotation notes with a custom template.
  4. Latex Suite and Completr, if the vault contains math-heavy notes.
  5. Tasks, if the user wants project management inside Obsidian.
  6. LanguageTool Integration, Spaced Repetition, and Language Learner, if writing polish, review, or language study are part of the workflow.
  7. Marp Slides only when presentation drafting becomes necessary.

Installed but not currently active

The folder .obsidian/plugins/marp-slides/ is present, but marp-slides is not enabled in the active community plugin list.

Plugin What it does When to enable
Marp Slides 0.45.6 (marp-slides) Creates Markdown-based Marp presentations in Obsidian. Enable when you want to draft slides directly from vault notes.

Useful active Obsidian core plugins

Core plugins are built into Obsidian. In this vault, useful active ones include:

Core plugin Why it matters for agentic research
File explorer Lets humans check exactly where agents placed notes.
Global search Finds concepts, citekeys, TODOs, and broken assumptions across the vault.
Graph, Backlinks, Outgoing links Show whether new notes are connected to existing research context.
Canvas Useful for mapping projects, paper relationships, and research plans.
Tag pane Makes the tag system visible and discourages random new tags.
Page preview Lets users inspect links without losing context.
Daily notes Supports research logs and daily capture.
Templates Keeps recurring note formats consistent.
Note composer Helps split or merge notes after review.
Outline Makes long literature and concept notes easier to navigate.
Word count Useful for abstracts, statements, and draft sections.
Slides Enables simple slide-style previews from Markdown.
File recovery Adds a second recovery layer besides Git.
Bases Supports structured database-like views inside Obsidian.

MCP integrations used here

MCP servers are not Obsidian plugins, but they are central to the agent workflow.

MCP server Config evidence What it does
Obsidian MCP via mcpvault .mcp.json and .codex/config.toml point it at e:\note. Lets agents list, inspect, and potentially modify vault files through a vault-aware interface.
Zotero MCP via zotero-mcp.exe .mcp.json and .codex/config.toml set ZOTERO_LOCAL=true. Lets agents search the local Zotero library and retrieve reference metadata without guessing.

Keep these two integrations aligned. If Claude Code uses .mcp.json and Codex uses .codex/config.toml, both should point to the same vault and the same Zotero executable.

Codex-side plugins/connectors

The Codex environment for this workflow can also expose task-specific plugins. The ones relevant to a research workflow are:

Codex plugin/connector What it does When to use
Zotero Searches the local Zotero library, exports BibTeX, inserts citations, and reads Zotero metadata through the local Zotero app. Use whenever a task involves citations, literature notes, BibTeX, or Zotero annotations.
Spreadsheets Creates, edits, analyzes, and visualizes .xlsx, .csv, .tsv, or Google Sheets-ready spreadsheets. Use for experiment logs, sample tables, measurement summaries, and data-cleaning sheets.
Presentations Creates and edits slide decks such as PowerPoint/PPTX. Use for group-meeting slides, conference talks, and research presentations.
Slack Reads and writes Slack context through the configured integration. Use only if the user’s research collaboration actually happens in Slack.

For a new user, these Codex plugins are optional. Start with Claude Code in VS Code and the two MCP servers. Add Codex plugins when the user has a clear need, such as producing a slide deck or synchronizing citations.

Agent instruction files

Use root-level instruction files to make every agent obey the same research rules.

Recommended minimum:

1
2
AGENTS.md       # Rules for Codex-style agents
CLAUDE.md       # Rules for Claude Code

These two files can contain the same rules. The important part is that they are explicit, local, and versioned with the vault.

For an academic note vault, the most important rules are:

  • Do not invent citations, DOI values, arXiv IDs, authors, years, or bibliographic metadata.
  • Literature metadata must come from Zotero, existing notes, or text explicitly supplied by the user.
  • If a paper is not found in Zotero, say so directly.
  • Do not modify .obsidian/ unless the user explicitly requests it.
  • Do not delete or rename existing notes unless the user explicitly requests it.
  • Respect directory ownership. For example, research notes may be writable while administrative or template folders may be read-only.
  • Let the existing Git or Obsidian Git workflow manage commits if that is how the vault is configured.

Example AGENTS.md skeleton:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# AGENTS.md - Research vault rules

You are maintaining a local Obsidian research vault. The working directory is the vault root.

## Hard rules

- Do not invent citations, DOI values, arXiv IDs, authors, years, or bibliographic metadata.
- All bibliographic information must come from Zotero, existing vault notes, or user-provided text.
- If Zotero does not contain a requested paper, say "not found in Zotero" and do not guess.
- Do not modify `.obsidian/`.
- Do not delete or rename existing notes unless explicitly requested.
- Preserve existing Obsidian syntax: wikilinks, embeds, callouts, tags, highlights, block IDs, and LaTeX.

## Writing style

- Literature notes may mix Chinese and English, with technical terms kept in English.
- Concept notes should use clear explanation plus equations when useful.
- Keep links to related notes using Obsidian wikilinks.

Then copy or adapt the same content into CLAUDE.md.

MCP configuration

MCP is the bridge that lets agents interact with local tools. In this workflow, the two most useful MCP servers are:

  • Obsidian MCP, for vault-aware reads and writes.
  • Zotero MCP, for local reference search and citation metadata.

Shared MCP file

Claude Code commonly uses a root .mcp.json file. A Windows example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "mcpServers": {
    "zotero": {
      "command": "C:\\Users\\YOUR_NAME\\AppData\\Roaming\\Python\\Python312\\Scripts\\zotero-mcp.exe",
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    },
    "obsidian": {
      "command": "mcpvault",
      "args": ["E:\\path\\to\\your\\vault"]
    }
  }
}

For macOS or Linux, replace the executable path and vault path with your local paths.

Codex config

Codex can keep MCP server configuration in .codex/config.toml:

1
2
3
4
5
6
7
8
9
[mcp_servers.obsidian]
command = "mcpvault"
args = ["E:\\path\\to\\your\\vault"]

[mcp_servers.zotero]
command = "C:\\Users\\YOUR_NAME\\AppData\\Roaming\\Python\\Python312\\Scripts\\zotero-mcp.exe"

[mcp_servers.zotero.env]
ZOTERO_LOCAL = "true"

Claude local permissions

Start with narrow Claude Code permissions and expand only when needed:

1
2
3
4
5
6
7
8
{
  "permissions": {
    "allow": [
      "mcp__obsidian__get_vault_stats",
      "mcp__obsidian__list_directory"
    ]
  }
}

Add write tools only when you trust the workflow and have version history enabled.

⚠️ 路径纪律：路径是工作流的一部分。如果 vault 移动了，记得同步更新 .mcp.json、.codex/config.toml 和编辑器工作区设置。过期的 MCP 路径会让 Agent 操作错误的文件夹，或者静默失败。

Zotero as the citation authority

For academic work, Zotero should be the only source of bibliographic truth unless the user explicitly provides metadata.

Recommended practice:

  • Add papers to Zotero first.
  • Clean title, author, venue, year, DOI, arXiv ID, and PDF attachment in Zotero.
  • Use Zotero MCP to search before creating a literature note.
  • Export or sync JSON/BibTeX into a read-only folder such as zotero-export/ or zoterocite/ if your Obsidian plugins need it.
  • Use a consistent citekey format for literature notes, such as @citekey.md.

Example literature-note rule:

1
2
If creating a literature note, first verify the paper in Zotero.
If it is not present, report "not found in Zotero" and ask whether to proceed from user-provided metadata.

Example literature-note template:

在本 vault 中，修改文献笔记格式之前，也请对照 template/zotero-notes-template 中的 Zotero 笔记模板。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
---
type: literature
citekey:
title:
authors:
year:
doi:
url:
tags: []
---

# Title

## One-sentence summary

## Background and question

## Key results

## Method

## Relation to my research

## Possible uses

## Questions and thoughts

## Zotero annotations

## Links

Obsidian conventions

A good agent workflow depends on preserving Obsidian syntax instead of flattening notes into plain Markdown.

Important syntax:

Syntax Meaning
[[note]] Link to another note
[[note|alias]] Link with display alias
![[file.png]] Embed image or note
> [!note] Callout
#tag Tag
==text== Highlight
^block-id Block reference target
$...$, $$...$$ LaTeX math

Agents should preserve these forms when editing. They should not rewrite wikilinks into ordinary Markdown links unless the target is external.

Daily workflow

1. Capture sources

When you find a paper:

  1. Save it to Zotero.
  2. Attach the PDF.
  3. Check metadata.
  4. Add tags or collections in Zotero.
  5. Sync or export metadata if your vault uses a Zotero export folder.

2. Create or update notes

Ask an agent to create notes only after it has checked the vault and Zotero.

Prompt example:

1
Read AGENTS.md first. Search Zotero for "<paper title>". If found, create a literature note using the vault template. Use only Zotero metadata and the paper text I provide. Link it to related notes if they already exist.

3. Build concept notes

Concept notes should connect papers, equations, and your own questions.

Prompt example:

1
Read AGENTS.md and inspect related notes under physics/. Create a concept note explaining <topic>. Use Chinese explanation with English technical terms. Include LaTeX for the key equations and add Obsidian wikilinks to existing related notes.

4. Review in VS Code

Use VS Code for:

  • Checking changed files.
  • Reviewing diffs before keeping a large agent edit.
  • Searching across the vault.
  • Running scripts or formatters when the vault includes code.
  • Fixing encoding or path issues.

5. Read in Obsidian

Use Obsidian for:

  • Checking whether wikilinks resolve.
  • Seeing graph/context.
  • Reading callouts, embeds, and LaTeX as rendered notes.
  • Moving from a literature note to a concept note.
  • Writing human reflections after the agent draft.

6. Let Git protect the vault

Use Git or Obsidian Git for automatic version history. This matters because agents can make large edits quickly.

Recommended rule for agents:

1
Do not manually commit unless the user explicitly asks. Report changed files and verification instead.

Codex and Claude Code together

Use Claude Code first because it sits naturally inside VS Code, where the new user can see files, terminals, and diffs. Use Codex after the folder already has good instructions, stable MCP paths, and one or two successful smoke tests.

You do not need both agents doing the same thing at the same time. A clean division is:

Situation Suggested agent pattern
First setup in a new folder Claude Code reads this Markdown guide and drafts CLAUDE.md, AGENTS.md, .mcp.json, and local settings
First note-writing smoke test Claude Code creates a small scratch note while the user watches the VS Code diff
Multi-file vault cleanup Codex drafts or verifies after Claude Code has established the rules
Literature note from Zotero One agent writes, the other checks citation discipline
Code or script in the vault Codex edits and runs checks
Long prose note Claude Code drafts, Codex verifies links/files if needed
Unclear task Ask one agent to inspect and propose a plan before edits

Practical rules:

  • Do not let two agents edit the same file simultaneously.
  • Before switching agents, ask the new agent to read AGENTS.md or CLAUDE.md and summarize the current state.
  • Keep task boundaries small: one note, one folder, or one workflow at a time.
  • Use the second agent as a reviewer when citation integrity or file safety matters.
  • Treat this Markdown file as the onboarding specification. Once the workflow exists, AGENTS.md and CLAUDE.md become the day-to-day operating rules.

Good handoff prompt:

1
Read AGENTS.md and inspect the current diff. Do not edit yet. Summarize what changed, identify any citation or Obsidian-syntax risks, and list the minimal fixes needed.

Prompt patterns

Start-of-session prompt

1
Read AGENTS.md first. Then inspect the vault structure and the files relevant to my request. Do not modify `.obsidian/`. Before editing, tell me which files you plan to touch.

Literature note prompt

1
Search Zotero for "<title or DOI>". If found, create `@citekey.md` using the literature-note template. Do not invent missing metadata. Include a short summary, key results, methods, relation to my research, questions, Zotero annotations if available, and links to existing related notes.

Concept note prompt

1
Create a concept note about <topic>. Use existing vault notes as context. Preserve Obsidian wikilinks and LaTeX. Add a warning callout for assumptions and a question callout for open problems.

Meeting-note prompt

1
Turn these raw meeting notes into a clean group-meeting note. Preserve technical details, equations, and action items. Link to existing literature or concept notes only when the target note already exists.

Review prompt

1
Review this note like a research assistant. Prioritize factual errors, unsupported citations, broken links, unclear equations, and missing assumptions. Give findings first with file and line references.

Verification checklist

Before accepting an agent edit, check:

  • The agent read the local instruction file.
  • No citations or bibliographic fields were invented.
  • Any cited paper was verified in Zotero or already existed in the vault.
  • No .obsidian/ files were modified.
  • No existing notes were deleted or renamed without permission.
  • Obsidian wikilinks, embeds, callouts, LaTeX, and tags were preserved.
  • New notes are in the correct folder.
  • VS Code diff shows only expected changes.
  • Obsidian renders the note correctly.
  • Git or Obsidian Git has a recoverable version history.

Common failure modes

Failure mode Prevention
Fake citation metadata Require Zotero lookup before literature-note creation
Agent edits Obsidian config Put .obsidian/ in the hard rules as no-touch
Two agents overwrite each other Assign one writer and one reviewer
Broken links after note moves Avoid renaming and moving notes unless explicitly requested
Stale Zotero export Refresh the export folder after large Zotero changes
Over-broad prompts Ask for one concrete note or folder at a time
Hidden tool path mismatch Keep .mcp.json and .codex/config.toml updated with the vault path
Loss of work Use Obsidian Git or regular Git history

Minimal setup checklist for a new user

  1. Create or choose one research folder as the vault root.
  2. Open that folder in VS Code.
  3. Install or enable Claude Code for VS Code.
  4. Put this file, Agentic research workflow.md, in the folder.
  5. Ask Claude Code to read this file and draft the workflow files.
  6. Open the same folder in Obsidian.
  7. Install and configure Zotero.
  8. Install the minimum Obsidian plugins: Git and Zotero Integration.
  9. Add BibNotes Formatter if the user wants Zotero annotation import templates.
  10. Add Latex Suite and Completr if the user writes math-heavy notes.
  11. Add Tasks if project tracking should live inside Obsidian.
  12. Add .mcp.json for Claude Code.
  13. Add .codex/config.toml for Codex only after Claude Code works.
  14. Configure Zotero MCP and Obsidian MCP paths.
  15. Enable Git or Obsidian Git for recovery.
  16. Test that Claude Code can list vault files.
  17. Test that Claude Code can search Zotero for a known paper.
  18. Ask Claude Code to create one small note in a writable folder.
  19. Review the diff in VS Code.
  20. Open the note in Obsidian and check rendering.
  21. Add Codex and repeat the same smoke tests.

First task to try

Use a low-risk prompt:

1
Read AGENTS.md. Inspect the vault structure. Create a short note called `agent workflow smoke test.md` in a writable scratch or todo folder. Include one Obsidian callout, one wikilink to an existing note, and no citations. Do not modify any other files.

If that works, try a Zotero-backed literature note:

1
Read AGENTS.md. Search Zotero for a paper I already have: "<known title>". If found, create a literature note from Zotero metadata only. If not found, say "not found in Zotero" and stop.

Why this workflow works

The workflow works because it gives every participant the same context:

  • Humans read and write in Obsidian.
  • Agents read the same folder and follow local rules.
  • VS Code exposes exact file changes.
  • Zotero protects citation integrity.
  • MCP gives agents structured access to local tools.
  • Git gives rollback.

The result is not a fully automatic research system. It is a controlled collaboration loop: Zotero for truth, Obsidian for thought, VS Code for inspection, and agents for careful drafting, refactoring, searching, and verification.