Claude Code Documentation & Context Management Guide

A reference guide for structuring project documentation and managing context effectively with Claude Code.

---

Project Documentation Structure

Recommended /docs Folder

/docs
├── ARCHITECTURE.md      # System overview, key patterns, data flow
├── PRD.md               # Product requirements (what & why)
├── API.md               # API contracts, endpoints, request/response shapes
├── CONVENTIONS.md       # Code style, naming, file organization rules
├── DECISIONS.md         # Architecture Decision Records (ADRs)
└── /specs
    └── feature-name.md  # Per-feature specifications as needed

iOS Note: Consider adding MODELS.md to document Core Data schemas or Swift model relationships, and NAVIGATION.md if using Coordinator pattern or complex navigation flows.

Documentation File Reference

File	Purpose	When Claude Code Needs It
ARCHITECTURE.md	Component relationships, tech stack, module boundaries	Starting new features, refactoring, understanding system design
PRD.md	User stories, acceptance criteria, project scope	Feature implementation, prioritization questions
API.md	Contracts between services/modules, endpoint definitions	Building integrations, API endpoints, data parsing
CONVENTIONS.md	Code patterns, naming rules, file organization	Any code generation task
DECISIONS.md	Context on past architectural choices and tradeoffs	When Claude suggests something you've already evaluated

iOS Note: In ARCHITECTURE.md, document your chosen patterns (MVVM, TCA, VIPER, etc.), dependency injection approach, and how you handle SwiftUI vs UIKit boundaries. In CONVENTIONS.md, specify Swift style rules: async/await vs Combine, error handling patterns, and whether you use @MainActor explicitly or rely on inference.

Referencing Docs in CLAUDE.md

Don't enumerate every file. Instead, teach Claude Code when to look:

## Documentation
- Before implementing a feature, read the relevant spec in `/docs/specs/`
- Follow patterns documented in `/docs/ARCHITECTURE.md`
- Code style rules are in `/docs/CONVENTIONS.md` — always follow these
- If unsure why something is built a certain way, check `/docs/DECISIONS.md`

Providing Context Mid-Session

Point to specific docs when starting a task:

• "Read /docs/specs/auth-flow.md then implement the login screen"
• "Check /docs/API.md for the response shape before parsing"

This keeps context focused — load only what's relevant to the current task.

---

Context Management

File Organization

• Maintain a /docs folder with specs, architecture docs, and API contracts for Claude Code to reference
• Use .claudeignore to exclude irrelevant files (build artifacts, node_modules, large assets) and keep context focused
• Commit frequently — Claude Code works better with clean git state and can reference recent commits

iOS Note: Your .claudeignore should include:

DerivedData/
*.xcodeproj/xcuserdata/
*.xcworkspace/xcuserdata/
Pods/
.build/
*.ipa
*.dSYM.zip

Also consider ignoring large asset catalogs if they're bloating context.

Context Hygiene

• Start fresh sessions for unrelated tasks — context pollution degrades output quality
• Summarize key decisions at session end if you'll continue the work later

---

Prompting Patterns

Be Explicit About Scope

• ✅ "Edit only UserService.swift"
• ❌ Letting it touch multiple files without guidance

Reference Files Directly

• "Look at src/api/auth.ts and follow that pattern"
• "Match the style in Components/Button.tsx"

iOS Note: Point to your established patterns explicitly:

• "Follow the ViewModel pattern in Features/Profile/ProfileViewModel.swift"
• "Use the same network request structure as Services/APIClient.swift"
• "Match the SwiftUI view composition in Components/PrimaryButton.swift"

State Constraints Upfront

• "Don't add new dependencies"
• "Keep this under 50 lines"
• "Use the existing error handling pattern"

Ask for Plans First

• "Outline your approach before writing code"
• Allows you to course-correct before implementation

---

Workflow Practices

Version Control Integration

• Use git worktrees for parallel Claude Code sessions on different features
• Checkpoint with commits after successful changes for clean rollback points
• Review diffs before accepting — treat output like a PR from a teammate

Validation Loop

• Run tests after changes: "Run the test suite and fix any failures"
• Include linting/formatting as part of the workflow
• Request self-review: "Review what you just wrote for edge cases"

iOS Note: Be specific about test targets: "Run unit tests in MyAppTests" vs "Run UI tests in MyAppUITests". For SwiftUI previews, ask Claude Code to verify preview builds compile: "Make sure the preview provider still compiles". If using SwiftLint, include it in your validation: "Run swiftlint and fix any violations".

---

CLAUDE.md Essentials

Your CLAUDE.md file should include:

## Project Overview
Brief description of what the project does and its core purpose.

## Tech Stack
- Language/framework versions
- Key dependencies
- Build tools

## Architecture
High-level structure, or pointer to `/docs/ARCHITECTURE.md`

## Documentation
- Where to find specs, conventions, and decisions
- When to reference each doc

## Code Conventions
- Naming patterns
- File organization rules
- Patterns to follow (and anti-patterns to avoid)

## Common Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

iOS Note: Your CLAUDE.md tech stack section should specify:

• Swift version and minimum iOS deployment target
• SwiftUI vs UIKit (or hybrid approach)
• Dependency manager (SPM preferred, CocoaPods if legacy)
• Async patterns: async/await, Combine, or both

For common commands, include:

- Build: `xcodebuild -scheme MyApp -configuration Debug build`
- Test: `xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'`
- Lint: `swiftlint` (if using SwiftLint)

Also document Xcode-specific context Claude Code can't infer: build configurations, custom schemes, and any Run Script phases that affect codegen.

---

Xcode 26.3 Integration

With Xcode 26.3's native Claude Agent support via MCP, some workflows shift significantly.

Key Benefits Over Terminal Claude Code

Visual Verification

• Claude can capture and analyze Xcode Previews directly
• Sees what the UI actually looks like, not just the code
• Iterates based on visual output — transformative for SwiftUI development

Full IDE Access

• Builds projects natively (not shelling out to xcodebuild)
• Runs test suites and iterates on failures automatically
• Updates project settings, schemes, and build configurations
• Accesses Xcode's live documentation (always current APIs)

Project Understanding

• Explores full file structure with Xcode's awareness of targets, groups, and dependencies
• Understands project metadata (deployment targets, capabilities, entitlements)
• Knows which files belong to which targets — something terminal Claude infers imperfectly

Workflow

• Automatic milestones on every change — easy revert to any point
• Step-by-step transparency of agent actions
• No manual context window management — Xcode handles what Claude sees

What Becomes Less Critical

Previous Practice	Why It Changes
.claudeignore configuration	Xcode controls context exposure via MCP
Manual xcodebuild commands in CLAUDE.md	Claude builds natively through Xcode
Explicit file references	Claude explores the project autonomously
Describing expected UI behavior	Claude can see Previews directly

What Still Matters

Documentation	Why It's Still Valuable
ARCHITECTURE.md	High-level intent and boundaries — faster than exploration
CONVENTIONS.md	Style preferences aren't inferrable from code alone
DECISIONS.md	Why you rejected alternatives — prevents re-litigating
PRD.md / specs	Product requirements aren't in the codebase
API.md	External service contracts

New Considerations for Xcode 26.3

• Test organization matters more — Claude can run them, so well-structured test suites become more leverageable
• Preview coverage pays off — Claude uses Previews for visual verification; comprehensive previews = better iteration
• Documentation is agent-agnostic — MCP means Claude, Codex, or future agents all benefit from the same /docs folder

When to Use Terminal Claude Code Instead

Scenario	Why Terminal Wins
Multi-repo / monorepo work	Xcode scopes to one project
Non-Apple platforms	Xcode is Apple-only
Backend + iOS in tandem	Terminal can span both codebases
Custom toolchains	More control over environment
Parallel sessions on same project	Xcode requires git worktree workaround

---

Quick Reference

Do

• ✅ Keep documentation current and accessible
• ✅ Be specific about scope and constraints
• ✅ Ask for plans before implementation
• ✅ Commit frequently for clean rollback points
• ✅ Run tests and lint after changes
• ✅ Start fresh sessions for unrelated work

Don't

• ❌ Stuff all docs into context at once
• ❌ Let Claude Code modify files without explicit guidance
• ❌ Skip reviewing diffs before accepting changes
• ❌ Continue polluted sessions across unrelated tasks
• ❌ Forget to checkpoint successful changes with commits