症状： Cursor Agent just read a README inside node_modules and wrote conclusions into your production config—or Claude Code “successfully” edited a file in the sandbox, but your real repo never changed after refresh.
根本原因： Modern AI Agents rarely touch your disk directly. They operate on a Virtual File System (VFS): paths and read/write APIs exist, but boundaries, persistence, and permissions differ from “real files.”
In July 2026 we debugged three teams: one treated Agent logs showing /workspace/src as a local path; one ran CI without a workspace mount so “cache deleted” only cleared a memory view; one indexed MCP file snapshots as ground truth and served stale RAG. This guide explains why VFS exists, how virtual differs from real files, and how to design boundaries. Figures current as of 2026-08-08.
Quick Answer：Agent ログの「ファイル」はディスク上ではないことが多い
| 困惑点 | 一言で | 今すぐ確認 |
|---|---|---|
| Agent read a file I don’t have locally | Likely a VFS mapped path or MCP/remote repo snapshot | Compare log paths with pwd and mount table |
| Sandbox edit succeeded, repo unchanged | Write went to a temp overlay, not the real workspace | Is sandbox writable and mounted to the same dir? |
| Why not let Agent read the whole disk? | Security and context cost—VFS enforces allowlists | List tool-permitted root paths |
| Virtual file vs string in memory | Virtual files have path, metadata, version for tools | Presence of path, mtime, hash |
| Vector DB chunks—which type? | Logical file view, usually not directly writable | Separate “retrieval snippets” from editable workspace |
なぜ AI Agent に仮想ファイルシステムが必要か？
Models cannot “open a folder” natively—they reach the world through tools. VFS is the mediation layer between tools and real storage, usually solving four problems:
- Security boundary: allow
/workspace, block~/.ssh, cloud creds, customer volumes. - Context budget: a 50GB repo vs thousands of tokens—VFS slices on demand: first 200 lines, globs, diffs not whole files.
- Reproducibility: snapshots and overlays tagged with
snapshot_id—“which file version did the Agent see?” - Cross-environment consistency: logical root
/workspaceunifies Mac, cloud Mac, and CI paths.
Case: a team let Agent
catproduction logs; API keys landed in Claude context. Read-only VFS + path allowlist stopped incidents and cut tokens ~35%.
This complements long context—see Kimi K3 1M と Agent の境界: even with a huge window, VFS still decides what loads and at what granularity.
実ファイル vs 仮想ファイル：四層比較
“Virtual” is not fake text—it is a file interface via API, backed by disk, memory, remote Git, vectors, or hybrids.
| Dimension | Real file (OS) | Virtual file (Agent VFS) |
|---|---|---|
| Storage | Local disk, NFS, object mount | Subset or projection of the above |
| Persistence | Survives reboot by default | Temp overlay, session cache, read-only snapshot |
| Path semantics | Absolute path → inode | Logical remap (container /workspace) |
| Metadata | mtime, ACL from kernel | Synthetic content_hash, source_commit |
| Permissions | Unix ACL, OS sandbox | Tool policy: read-only search vs editable |
| Consistency | Locks and races across processes | Framework may snapshot-read |
Memory strings are not virtual files unless the framework assigns a path other tools can read(path). Otherwise they are chat context—why frameworks write into VFS or workspace.
| Operation | On real file | On typical Agent VFS |
|---|---|---|
read | Disk blocks | Snapshot; truncation; may trigger RAG |
write | Direct inode change | Overlay; may need user confirm |
delete | Permanent without backup | May delete view only |
list | Directory entries | May hide .git, node_modules |
五つの一般的な仮想ファイル形態（2026 実践）
| Shape | Typical products | What Agent sees | Risk |
|---|---|---|---|
| Workspace mount | Cursor, Claude Code, Devin-like | Project root read/write | Mount too wide; secrets included |
| Sandbox overlay | Docker, macOS sandbox, WASM | Read-only base + writable layer | Overlay not merged → false success |
| Remote repo snapshot | Cloud Mac, GitHub API, MCP git | File tree at a commit | Drift from unpushed local work |
| Logical doc chunks | RAG, ナレッジベース PDF パイプライン | Chunks with source_id, not full files | Chunk treated as whole file; stale versions |
| Structure index view | コード知識グラフ | Virtual paths to symbols and edges | Stale graph vs live code |
Benchmark (July 2026, three environments): same repo via local disk, Docker read-only + overlay, and MCP GitHub default branch—Agent awareness of unpushed API changes: 100%, 100%, 0%. Wrong VFS shape beats wrong model choice.
パスマッピングとサンドボックス：三つの失敗事例
Pitfall 1: container path ≠ host path
Logs say Edited /workspace/apps/api/src/main.ts—you won’t find /workspace on your Mac. Document logical root → host path mapping.
Pitfall 2: read-only mount + write tool
CI mounts read-only; Agent “simulates” success in memory. Verify with independent git status, not natural language.
Pitfall 3: treating retrieval as editable files
RAG chunks lack stable paths. Flow: retrieve → real read in workspace → edit.
Pitfall 4: unfiltered large directories
Listing / pulls node_modules and build artifacts. Configure VFS ignore_globs stricter than .gitignore.
AGENTS.md or .cursor/rules, same source as CI mount scripts.VFS・RAG・コードグラフの役割分担
- VFS (workspace): editable source of truth; “change this line”, run tests.
- RAG / Knowledge Base: non-editable slices; policies, tickets, cross-repo docs. Pollution risks: PDF ベクトル DB 品質.
- Code graph: virtual call graph; “who calls this API”. See 大規模リポのコード知識グラフ.
| Task | Prefer | Avoid |
|---|---|---|
| Edit implementation | VFS read/write | Only old retrieval chunks |
| Compliance PDF clause | RAG + source metadata | Glob entire disk for PDFs |
| Refactor blast radius | Code graph + selective read | Model reads whole repo |
| Long doc Q&A | Long context + VFS chapter read | Embed entire book in prompt |
七ステップチェックリスト：公開前と毎月
- Draw VFS boundary map: readable, writable, invisible paths.
- Verify path mapping in docs for container/remote vs local.
- Fake-write test: confirm disk actually changes after write.
- Align ignore rules: no
node_modules, secrets, huge binaries in list. - Separate retrieve vs edit: RAG → real read → code change.
- Record snapshot version: commit or
snapshot_idon remote/MCP views. - Audit sensitive reads: log attempts outside project root.
On remote cloud Mac, workspace mount should match local IDE Git state. See 30 分 AI 開発環境セットアップ for SSH and directory conventions.
シナリオ収束：コンピュートをどこに置くか
VFS itself needs no GPU, but parsing, indexing, sandbox overlays consume CPU and IO. Split: laptop for interactive VFS; dedicated runners for batch index and read-only eval; Macstripe cloud Mac for macOS-only chains with Agent over SSH/MCP on a logical root—not full disk exposure.
よくある質問
Is VFS just a “simulated disk”?
Not only. Agent VFS stresses permissions, projection, and tool APIs—the same logical file may come from Git snapshot, overlay, or retrieval chunk.
Can Agent read my whole hard drive?
Well-configured products default to no; misconfigured tools or shell can still leak. Use allowlists, OS sandbox, and read audits.
Why sandbox edit but repo unchanged?
Write hit overlay or session layer without merging to bind mount. Verify with git status.
Are RAG documents virtual files?
Logical file views with source ID and offsets—usually not writable. Code edits use workspace VFS.
Must remote and local VFS match?
Logically yes (same branch, same root convention). Physical paths can differ—document mapping and snapshot version.
まとめ
Prioritize VFS review if: multi-environment Agents, RAG or MCP remote repos, or “Agent said it edited but git is clean.”
Can defer if: small local repo, read-only Q&A, no auto-write tools.
Agents operate on file interfaces, not necessarily disk truth. Real files are persistent and OS-governed; virtual files are cropped and mapped for safety, context, and reproducibility.
関連記事： ナレッジベースとベクトル DB · コード知識グラフ · 長コンテキストと RAG の分担
