add article

2025-12-25 21:35:56 +07:00 · 2025-12-25 21:35:56 +07:00 · ff0ca43233
parent 357c1c4cc9
commit ff0ca43233
1 changed files with 555 additions and 0 deletions
--- a/2-outline/claude-virtual-filesystem-guide.md
+++ b/2-outline/claude-virtual-filesystem-guide.md
@ -0,0 +1,555 @@
+---
+slug: claude-virtual-filesystem-guide
+title: "Inside Claude's Sandbox: What Happens When Claude Creates a File"
+author: henry
+status: outline
+created: 2024-12-25
+updated: 2024-12-25
+content_type: debugging-story
+
+primary_keyword: "claude file creation"
+secondary_keywords: ["claude sandbox", "claude mcp filesystem", "claude outputs folder", "claude virtual filesystem"]
+---
+
+# Brief
+
+## Strategic Context
+
+### Why This Article?
+No one has documented Claude's internal sandbox filesystem structure in claude.ai. Users encounter frustration when files "disappear" or Claude creates files in the wrong location. This is Henry's first article — establishes technical credibility with an original investigation that provides real value.
+
+**Availability:** Code execution and file creation requires **paid plans** (Pro, Max, Team, Enterprise). Free plan only has Artifacts.
+
+### Target Reader
+- **Role:** AI-first developer using Claude Pro/Max with "Code execution and file creation" enabled
+- **Situation:** Using Claude for code generation, file creation, possibly with Filesystem MCP in Claude Desktop
+- **Pain:** Files created by Claude don't appear where expected; confusion between internal sandbox and Filesystem MCP
+- **Search query:** "claude file creation not working", "where does claude save files", "claude mcp vs sandbox"
+
+### Terminology Clarification (for article)
+| Term | What it means |
+|------|---------------|
+| "Code execution and file creation" | Official Anthropic name for sandbox feature in claude.ai |
+| Sandbox / Sandboxed environment | Ubuntu container where Claude runs code |
+| Artifacts | Interactive previews (HTML, React, SVG) — separate feature from file creation |
+| Filesystem MCP | External MCP server for local file access (Claude Desktop only) |
+| "Virtual filesystem" | NOT official term, but Claude understands it in conversation — tested in practice |
+
+### Success Metrics
+- Primary: Organic traffic from developers searching for Claude file issues
+- Secondary: Social shares from AI dev communities (Reddit, Twitter, Dev.to)
+
+---
+
+## SEO Strategy
+
+### Keywords
+| Type | Keyword | Notes |
+|------|---------|-------|
+| Primary | claude file creation | High intent, problem-focused |
+| Secondary | claude sandbox environment | Technical term users encounter |
+| Secondary | claude mcp filesystem | Confusion point we address |
+| Secondary | claude virtual filesystem | Descriptive, long-tail |
+
+### Search Intent
+User expects: practical explanation of where Claude stores files, how to find them, how to control file location.
+
+### Competition
+- Anthropic docs exist but are high-level, don't show internal paths
+- No articles specifically about `/mnt/user-data/` structure
+- Our angle: hands-on investigation with screenshots and "try it yourself" exercises
+
+### Unique Angle
+First-hand debugging story with reproducible experiments. Reader can follow along and discover the filesystem themselves.
+
+---
+
+## Content Requirements
+
+### Core Question
+**Where do files go when Claude creates them, and how do I make Claude save files where I actually want them?**
+
+### Must Cover
+1. Sandbox filesystem structure overview (key folders and their purposes)
+2. What happens when Claude creates a file (step by step)
+3. The `/mnt/user-data/outputs/` → sidebar connection
+4. Problem: Claude confusing internal sandbox vs Filesystem MCP (in Claude Desktop)
+5. Solution: how to direct Claude to the right tool
+6. **Two strategies for file workflows** (see below)
+7. "Try it yourself" experiments for readers
+8. Quick note: this requires paid plan (Pro+)
+
+### Two File Workflow Strategies (new section)
+
+**Strategy 1: Work in sandbox, save at end**
+- Work with files inside `/home/claude/` during conversation
+- Only move to `/mnt/user-data/outputs/` when done
+- Pros: Faster iteration, no filesystem noise, sandbox is temp anyway
+- Cons: Lose work if you forget to save, files not visible until end
+
+**Strategy 2: Save to local disk immediately (via Filesystem MCP)**
+- Claude saves directly to local filesystem via MCP
+- Pros: Files persist immediately, work directly with your project files
+- Cons: Requires MCP setup in Claude Desktop, can't use in claude.ai web
+
+### Must NOT Cover
+- MCP server installation guide (separate topic, just mention it exists)
+- API code execution tool (different product)
+- Artifacts deep dive (mention briefly for context on naming confusion)
+
+### Note on Artifacts vs Files (sidebar box)
+Users often confuse "artifacts" and "files":
+- **Artifacts** (June 2024): Interactive previews that render in sidebar — HTML, React, SVG, code snippets
+- **Files** (September 2025): Actual downloadable documents — .docx, .xlsx, .pdf, created via sandbox
+
+Artifacts had a highlight+edit feature (September 2024) where you could select code and click "Improve" or "Explain". This may have changed after the October 2025 UI update when Code Execution became default. The current interface separates Artifacts from file creation more clearly.
+
+### Unique Angle
+Personal debugging story: "I spent hours confused about where my files went. Here's what I discovered."
+
+### Banatie Integration
+- Type: none
+- Rationale: First Henry article, establish credibility first. No forced mentions.
+
+---
+
+## Structure Guidance
+
+### Suggested Flow
+1. **Opening hook:** The frustration — "Claude said it created the file. But where is it?"
+2. **The investigation:** How I started exploring with `view /` commands
+3. **The map:** Key folders explained with table
+4. **The gotcha:** Sandbox vs Filesystem MCP confusion
+5. **The fix:** Specific prompts that work
+6. **Two strategies:** Sandbox-first vs Local-first workflows
+7. **Try it yourself:** Commands readers can run
+8. **Quick reference:** Cheat sheet
+
+### Opening Hook
+Start with the specific frustration moment. First-person, relatable. No definitions.
+
+### Closing CTA
+"Now you know where Claude keeps its files. Go explore your own sandbox — and stop losing your work."
+
+---
+
+## Visual & Interactive Elements
+
+### Screenshots Needed
+1. Sidebar showing files in outputs folder
+2. Result of `view /mnt/user-data/` showing structure
+3. Example of Claude creating file "not in outputs" (the problem)
+
+### Code Snippets for Article
+```
+view /
+view /mnt/user-data/
+view /home/claude/
+```
+
+### "Try It Yourself" Exercises
+1. "Ask Claude: `view /mnt/user-data/` — what do you see?"
+2. "Ask Claude to create a test file. Check: did it appear in sidebar?"
+3. "If you have MCP configured, ask Claude to save via filesystem MCP specifically"
+
+---
+
+## Screenshot Flow (for Oleg to capture)
+
+Create a fresh chat with Code Execution enabled. Run these in sequence:
+
+```
+Step 1: "Show me the root filesystem structure with view /"
+Screenshot: The output showing available directories
+
+Step 2: "Show me what's in /mnt/user-data/"
+Screenshot: uploads/, outputs/ structure
+
+Step 3: "Create a simple test.txt file with 'hello world' content"
+Screenshot: Where Claude creates it (likely /home/claude/ or outputs/)
+
+Step 4: "Show me /mnt/user-data/outputs/"
+Screenshot: Verify file appears (or doesn't)
+
+Step 5: Check sidebar
+Screenshot: File appearing in download area
+
+Step 6 (if MCP configured in Claude Desktop): 
+"Use filesystem MCP to save a file to ~/Desktop/test-mcp.txt"
+Screenshot: Compare behavior — file goes to actual local disk
+```
+
+---
+
+## References
+
+### Official Documentation
+- https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude (main reference)
+- https://docs.claude.com/en/release-notes/claude-apps (timeline of features)
+
+### Research Sources
+- Personal investigation by author
+- Simon Willison's analysis: https://simonwillison.net/2025/Sep/9/claude-code-interpreter/
+
+### Background Context (for author reference, not for article)
+- Artifacts launched June 2024, got highlight+edit September 2024
+- "Analysis tool" (JS-based) launched October 2024
+- Code Execution (Python/Node sandbox) replaced Analysis tool September 2025
+- October 2025: Code Execution became default for paid plans, UI changed
+- Users report highlight+edit feature may work differently now
+
+### Competitor Articles
+- None directly covering this topic (unique content opportunity)
+
+---
+
+**Brief created:** 2024-12-25
+**Ready for:** @architect
+
+---
+
+# Outline
+
+## Pre-Writing Notes
+
+**Author:** henry
+**Voice reference:** style-guides/henry-technical.md
+**Word target:** 1200 words (range: 800-1500)
+**Content type:** debugging-story
+
+Key style points from Henry's guide:
+- Opening: Start with problem/frustration, not definitions (Section 2)
+- Sections: 150-300 words, paragraphs max 4 sentences (Section 2)
+- Code ratio: 20-30% for debugging stories (Section 4)
+- Closing: Practical next step, "Go build something." (Section 2)
+- Voice: Direct, confident, first-person, "Here's the thing about..." (Section 1)
+
+---
+
+## Article Structure
+
+### H1: Inside Claude's Sandbox: What Happens When Claude Creates a File
+*Contains primary keyword: "claude file creation"*
+
+---
+
+### Opening (120-150 words)
+
+**Purpose:** Hook reader with professional curiosity, promise deep understanding
+
+**Approach:** First-person exploration angle. Henry digs deeper because he wants to understand the system, not because he's lost.
+
+**Must include:**
+- Moment of curiosity (found file easily, but wanted to understand the system)
+- Professional interest signal — "how does this actually work?"
+- Promise: "Here's what I discovered when I mapped the whole thing."
+
+**Hook angle (Option A — curiosity):**
+> "Claude created the file. I found it in the sidebar in 5 seconds. But then I wondered — where is it physically? What's the filesystem structure inside? I went exploring."
+
+**Hook angle (Option B — scaling up):**
+> "When you start working with Claude on real projects, you eventually hit the question: how exactly is its filesystem organized? I decided to figure it out."
+
+**Transition:** "Let me show you what's actually happening under the hood."
+
+---
+
+### H2: The Quick Answer (80-100 words)
+
+**Purpose:** Give impatient readers the core answer immediately
+
+**Must cover:**
+- Claude runs in Ubuntu sandbox container
+- Key path: `/mnt/user-data/outputs/` = sidebar downloads
+- `/home/claude/` = temp workspace (disappears)
+
+**Structure:**
+1. One-liner: where files actually go
+2. Why some files "disappear"
+3. Tease: "But there's more to it. Let me show you the full map."
+
+**Note:** This follows Henry's "don't bury the lede" principle.
+
+---
+
+### H2: The Filesystem Map (200-250 words)
+
+**Purpose:** Complete reference of sandbox structure
+
+**Must cover:**
+- `/mnt/user-data/uploads/` — your uploaded files
+- `/mnt/user-data/outputs/` — files that appear in sidebar
+- `/home/claude/` — temp working directory
+- `/mnt/skills/` — Claude's built-in capabilities
+- Note: `/mnt/project/` for Projects feature
+
+**Structure:**
+1. Brief intro: "Here's the full structure I mapped out."
+2. Table with 4-5 key directories
+3. Key insight: only `/mnt/user-data/outputs/` = downloadable
+
+**Table format:**
+| Path | What's there | Persists? |
+|------|--------------|-----------||
+| `/mnt/user-data/uploads/` | Your uploaded files | Session |
+| `/mnt/user-data/outputs/` | Files for download | Session |
+| `/home/claude/` | Claude's workspace | ❌ No |
+| `/mnt/skills/` | Built-in capabilities | Read-only |
+
+**Code example:**
+```
+view /mnt/user-data/
+```
+Shows: uploads/, outputs/ structure
+
+**Transition:** "So why do files sometimes not appear in your sidebar?"
+
+---
+
+### H2: The Problem: Where Did My File Go? (150-180 words)
+
+**Purpose:** Explain the common frustration point
+
+**Must cover:**
+- Claude sometimes creates in `/home/claude/` (temp, not visible)
+- Files there won't appear in sidebar
+- Claude "forgets" to move to outputs
+- Second issue: Filesystem MCP confusion (Claude Desktop)
+
+**Structure:**
+1. The problem: Claude creates file in wrong place
+2. Why it happens: `/home/claude/` is default working dir
+3. Extra confusion: MCP vs sandbox (brief mention)
+
+**Key insight:**
+> "Claude's sandbox resets between conversations. If a file is in `/home/claude/` and you close the chat — it's gone."
+
+**⚠️ TODO:** Verify this claim with testing. Need to confirm sandbox reset behavior.
+
+**Transition:** "Here's how to make sure your files end up where you can actually get them."
+
+---
+
+### H2: The Fix: How to Direct Claude (150-200 words)
+
+**Purpose:** Give actionable solution
+
+**Must cover:**
+- Explicit instruction: "save to /mnt/user-data/outputs/"
+- Example prompts that work
+- For MCP users: specify "use filesystem MCP" vs sandbox
+
+**Structure:**
+1. What to say to Claude (prompt examples)
+2. For MCP users: disambiguation
+
+**Prompts that work:**
+```
+"Create the file and save it to /mnt/user-data/outputs/"
+```
+
+```
+"Copy this file to /mnt/user-data/outputs/"
+```
+
+```
+"Use filesystem MCP to save to ~/Projects/myapp/image.png"
+```
+
+**Transition:** "Now, which approach should you actually use?"
+
+---
+
+### H2: Two Strategies for File Workflows (200-250 words)
+
+**Purpose:** Help reader choose their approach based on workflow type
+
+**Must cover:**
+- Strategy 1: Sandbox for iterative work
+- Strategy 2: MCP for automation
+- When to use each (clear criteria)
+
+**Structure:**
+
+**Strategy 1: Sandbox-first (iterative editing)**
+- Work in `/home/claude/` during conversation
+- Use `str_replace` tool for line-by-line edits
+- Copy to outputs when done
+- Pros: faster iteration, built-in editing tools, no filesystem noise
+- Cons: files not visible in sidebar until you copy them out
+- Best for: iterative work on a single file, multiple rounds of edits, refactoring
+
+**Strategy 2: MCP-first (automation)**
+- Claude saves directly to local filesystem via MCP
+- Pros: files persist immediately in your project, no extra step
+- Cons: no `str_replace` tool, requires MCP setup, Claude Desktop only
+- Best for: generating multiple files at once, scaffolding, automated workflows
+
+**Key difference to highlight:**
+> Sandbox has `str_replace` for precise line-by-line editing. MCP doesn't. Choose based on whether you need iteration or automation.
+
+**One-liner summary:**
+> "Sandbox for iteration. MCP for automation."
+
+---
+
+### H2: Try It Yourself (100-130 words)
+
+**Purpose:** Reader engagement, verification
+
+**Must cover:**
+- 3 quick commands to explore their own sandbox
+- What to look for
+
+**Exercises:**
+1. `"Show me view /mnt/user-data/"` — see your structure
+2. `"Create test.txt with 'hello' and show me where it went"` — test file creation
+3. `"List contents of /home/claude/"` — see temp workspace
+
+**Note:** Remind that this requires Pro+ plan.
+
+---
+
+### H2: Project Instructions for File Handling (150-180 words)
+
+**Purpose:** Give readers ready-to-use instructions they can add to Claude Projects
+
+**Must cover:**
+- Example instruction for sandbox-first workflow
+- Example instruction for MCP-first workflow
+- How to specify which tool to use
+
+**Example 1 — Sandbox-first (for iterative work):**
+```
+File handling:
+- Work with files in /home/claude/ during conversation
+- Use str_replace for edits
+- Copy final versions to /mnt/user-data/outputs/ before finishing
+```
+
+**Example 2 — MCP-first (for automation):**
+```
+File handling:
+- Use filesystem MCP to save files directly to project directory
+- Do not use sandbox for file operations
+- Save to: ~/Projects/[project-name]/
+```
+
+**Example 3 — Hybrid (explicit routing):**
+```
+File handling:
+- For iterative editing: use sandbox + str_replace, copy to outputs when done
+- For generating new files: use filesystem MCP to save directly to ~/Projects/
+- Always confirm which method before creating files
+```
+
+**Note:** These go in Project Instructions or system prompt.
+
+---
+
+### Callout Box: Artifacts ≠ Files (60-80 words)
+
+**Purpose:** Address common terminology confusion
+
+**Placement:** As sidebar/callout, possibly after "The Fix" or near end
+
+**Must clarify:**
+- Artifacts: interactive previews (HTML, React, SVG) — render in sidebar
+- Files: actual downloadable documents (.docx, .xlsx, .pdf)
+- Different features, different behavior
+
+---
+
+### Closing (80-100 words)
+
+**Purpose:** Wrap up with practical takeaway
+
+**Approach:** Henry-style direct ending. No fluff.
+
+**Must include:**
+- One-sentence summary of key insight
+- Clear CTA (explore your sandbox)
+- Sign-off phrase
+
+**Draft closing:**
+> "That's it. Claude's sandbox isn't magic — it's just Ubuntu with a specific folder structure. Know the paths, and you'll never lose a file again."
+>
+> "Now go explore your own sandbox. And maybe save that important file before you close the chat."
+
+---
+
+## Word Count Breakdown
+
+| Section | Words |
+|---------|-------|
+| Opening | 130 |
+| The Quick Answer | 90 |
+| The Filesystem Map | 220 |
+| The Problem | 160 |
+| The Fix | 180 |
+| Two Strategies | 230 |
+| Try It Yourself | 110 |
+| Project Instructions | 160 |
+| Callout: Artifacts ≠ Files | 70 |
+| Closing | 90 |
+| **Total** | **~1440** |
+
+*Target: 1200-1500 (debugging story range) ✓*
+
+---
+
+## Code Examples Plan
+
+| Section | Type | Purpose | Lines |
+|---------|------|---------|-------|
+| Filesystem Map | Command | Show structure | 1 |
+| Filesystem Map | Output | Example result | 4-5 |
+| The Fix | Prompt | Working instruction | 1 |
+| The Fix | Prompt | MCP instruction | 1 |
+| Try It Yourself | Commands | Reader exercises | 3 |
+
+*Code ratio: ~15-20% (appropriate for debugging story)*
+
+---
+
+## Visual Elements Plan
+
+| Element | Section | Description |
+|---------|---------|-------------|
+| Screenshot 1 | Filesystem Map | Output of `view /mnt/user-data/` |
+| Screenshot 2 | The Problem | File in sidebar (successful) |
+| Screenshot 3 | Try It Yourself | Optional: annotated sandbox structure |
+| Table | Filesystem Map | Directory reference |
+| Callout box | After The Fix | Artifacts vs Files clarification |
+
+---
+
+## SEO Notes
+
+- [x] H1 contains: "Claude" + "File" (variant of primary keyword)
+- [x] H2s with keywords: "Filesystem", "File Workflows"
+- [x] First 100 words include: "Claude", "file", "created" (primary keyword area)
+- [ ] Meta description: @writer to draft — focus on "where Claude saves files"
+
+---
+
+## Quality Gates for @writer
+
+Before submitting draft:
+- [ ] Opening starts with curiosity/professional interest, not frustration or confusion
+- [ ] "Here's the thing..." or similar Henry phrase used
+- [ ] All "Must include" items covered
+- [ ] Word counts within range per section
+- [ ] Table in Filesystem Map section present
+- [ ] Code examples complete and accurate
+- [ ] Project Instructions section has 3 ready-to-use examples
+- [ ] Callout box for Artifacts/Files distinction included
+- [ ] Closing has practical CTA, no fluff
+- [ ] First-person voice throughout
+- [ ] No forbidden phrases (see Henry guide)
+- [ ] ⚠️ Sandbox reset claim verified before publishing
+
+---
+
+**Outline created:** 2024-12-25
+**Ready for:** @writer