Context Files for AI Projects

Context files (.md files in your project directory) solve the scattered chat problem by creating persistent, version-controlled project memory that works across multiple AI tools.

Key insight: Your project context lives in files on your hard drive, not trapped in browser chat sessions.

The Problem

Traditional AI workflow:

• Chat in browser → lose context when chat ends
• Multiple chats on same project → scattered information
• Switch AI tools → re-explain everything
• No version control → can't track decisions
• Browser crashes → lose hours of work

Result: Paralyzed by context chaos.

The Solution: Context Files

One file per AI tool in your project directory:

my-project/
├── claude.md       # Claude's context
├── gemini.md       # Gemini's context
├── agents.md       # Codex/ChatGPT's context
├── src/
└── README.md

Each AI automatically loads its context file when launched in that directory.

Creating Context Files

Claude Code

bash
cd ~/projects/my-video-script
claude

Inside Claude session:

bash
/init

This creates claude.md:

• Analyzes project directory
• Describes purpose based on files present
• Documents current status
• Auto-loaded on future sessions

Gemini CLI

bash
cd ~/projects/my-video-script
gemini

Inside Gemini session:

bash
/init

Creates gemini.md with similar structure.

ChatGPT Codex

bash
cd ~/projects/my-video-script
codex

Inside Codex session:

bash
/init

Creates agents.md (Codex uses this naming convention).

Context File Structure

Example claude.md:

markdown
# Video Script: Terminal AI Guide

## Project Purpose
Educational video about using AI in the terminal instead 
of browser-based interfaces. Target audience: developers 
and power users frustrated with context limitations.

## Current Status
- ✅ Completed: Initial outline
- 🔄 In Progress: Script writing (segment 4 of 7)
- ⏳ Next: Record narration, send to editor

## Key Decisions
- Focus on practical workflows over theory
- Demo all three tools (Gemini, Claude, OpenCode)
- Include cost comparison table
- Target 15-20 minute runtime

## Important Files
- script-outline.md - Segment breakdown
- authority-hook.md - Opening hook (authority angle)
- discovery-hook.md - Alternative hook (discovery angle)
- critic-framework.md - Review criteria for brutal-critic agent

## Recent Work
- Deployed brutal-critic agent to review outline (rated 8.2/10)
- Decided to combine hooks instead of choosing one
- Added section on session-closer agent workflow

## Notes
- User prefers concise, actionable content
- Avoid technical jargon without explanation
- Include keyboard shortcuts reference

Auto-Loading Behavior

When you launch AI in a directory:

1. AI checks for context file (claude.md, gemini.md, etc.)
2. If found, loads content into initial context
3. You can immediately continue where you left off
4. No re-explaining project purpose

Example:

bash
# Day 1
cd ~/projects/coffee-blog
claude
> Write blog post intro about pour-over coffee

# Day 2
cd ~/projects/coffee-blog
claude
# claude.md auto-loads
> Continue the blog post with brewing instructions
# AI already knows project context!

Updating Context Files

Manual update:

markdown
Update claude.md to reflect:
- Finished segment 4
- Ready to record narration
- Decided on 16-minute target length

Automated update (agent):

markdown
Use @session-closer agent to:
- Summarize today's work
- Update claude.md, gemini.md, agents.md
- Commit changes to git

Multi-AI Synchronization

The killer feature: Multiple AI tools working on same project.

Setup:

bash
cd ~/projects/my-project

# Terminal 1
claude

# Terminal 2
gemini

# Terminal 3
codex

Each AI:

• Reads same project files
• Can update shared context files
• References each other's work
• Stored in version control

Workflow example:

markdown
# Terminal 1 (Claude)
Write authority-angle hook → authority-hook.md

# Terminal 2 (Gemini)
Research top 10 coffee methods → coffee-research.md

# Terminal 3 (Codex)
Review both files and suggest improvements

All working on same project simultaneously, no copy/paste between tools.

Keeping Files Synced

Strategy 1: Manual sync

markdown
# In any AI session
Sync all context files (claude.md, gemini.md, agents.md) 
to reflect script completion

Strategy 2: Session-closer agent

Create agent in Claude Code:

markdown
You are a session-closer agent. At end of work session:

1. Read current claude.md, gemini.md, agents.md
2. Summarize all work done today
3. Update all three context files consistently
4. Note key decisions and next steps
5. Commit to git with descriptive message

Your goal: Leave project in clean state for next session.

Usage:

markdown
@session-closer wrap up today's work

Agent handles all sync automatically.

Version Control Integration

Context files + Git = powerful workflow:

bash
# Initialize git in project
cd ~/projects/my-project
git init

# Work with AI
claude
> Do some work...
> Update claude.md

# Commit context changes
git add claude.md gemini.md agents.md
git commit -m "Completed script outline, deployed critic agent"

# Later: Review history
git log --oneline
git show <commit-hash>  # See what decisions were made

Benefits:

• Track project evolution
• Revert bad decisions
• See what you were thinking at any point
• Share project state with collaborators

Advanced Patterns

Project Checkpoints

Milestone commits:

bash
git add .
git commit -m "Milestone: Script approved by critic agent (8.6/10)"
git tag v1.0-approved-script

Restore to checkpoint:

bash
git checkout v1.0-approved-script

Cross-AI Delegation

Gemini does research (free), Claude does writing (paid):

markdown
# Terminal 1 (Gemini - free tier)
Research best NAS systems under $500
Write findings to nas-research.md
Update gemini.md

# Terminal 2 (Claude - paid)
Read nas-research.md
Write buyer's guide based on research
Reference gemini.md for research notes

Context File Templates

Create template for new projects:

markdown
# PROJECT_NAME

## Project Purpose
[What this project is about]

## Current Status
- ✅ Completed: 
- 🔄 In Progress: 
- ⏳ Next: 

## Key Decisions
- [Important decisions made]

## Important Files
- [Key project files]

## Recent Work
- [Latest activities]

## Notes
- [Anything important to remember]

Copy template to new project:

bash
cp ~/templates/context-template.md ~/projects/new-project/claude.md

Real-World Example

Video script project (from NetworkChuck video):

claude.md excerpt:

markdown
# Terminal AI Video Script

## Current Status
- Segment 5 complete (Claude Code agents feature)
- Brutal critic rated 8.2/10
- Concern: Segment 5 might be "feature dump" (retention drop risk)

## Key Decisions
- Include all 7 segments despite critic feedback
- Focus on practical workflows over theory
- Demo multiple tools simultaneously

## Agents Used
- brutal-critic: Reviews script segments
- session-closer: Syncs context files, commits to git
- research-agent: Gathers background info without bloating main context

Result:

• Clear project state visible in one file
• AI can reference past decisions
• Context persists across sessions
• Version controlled for safety

Best Practices

Initialize early:

bash
# As soon as you start a project
cd new-project
claude
/init

Update regularly:

• After completing tasks
• Before ending work session
• When making key decisions

Keep it concise:

• Don't let context files bloat
• Archive old notes to archive/ folder
• Focus on current status + key decisions

Sync before switching AIs:

markdown
Update all context files before I switch to Gemini

Commit often:

bash
git add *.md
git commit -m "Updated context: finished research phase"

Comparison: Context Files vs Browser Chats

Tips

Start every project with /init:

• Creates context file immediately
• AI learns project purpose from files
• Future sessions pick up automatically

Use session-closer agent:

• Automates end-of-day sync
• Ensures consistency across files
• Creates git commits automatically

Treat context files like code:

• Commit regularly
• Write descriptive commit messages
• Review diffs before committing

Leverage multi-AI workflows:

• Gemini for research (free)
• Claude for complex work (paid)
• All share same context files
• No vendor lock-in

Links

NetworkChuck Video: You've Been Using AI the Hard Way

• URL: https://www.youtube.com/watch?v=MsQACpcuTkU↗
• Summary: Introduces context file workflow as core feature of terminal AI usage
• Related: Claude Code with Agents, Gemini CLI, OpenCode