Skip to content

CONCEPTS.md

Latest commit

 

History

History
187 lines (143 loc) · 5.35 KB

CONCEPTS.md

File metadata and controls

187 lines (143 loc) · 5.35 KB
Raw

Concepts & Philosophy

This document explains the thinking behind this workflow system.

The Problem

Claude Code sessions are stateless. When you start a new session, Claude doesn't know:

  • What project you were working on
  • Where you left off
  • What decisions were made
  • What's next on your list

You end up re-explaining context every time.

The Solution

This workflow creates persistent context through:

  1. CLAUDE-INSTRUCTIONS.md - Per-project context that Claude reads at session start
  2. Session notes - Documentation of what happened
  3. /hello and /bye commands - Standardized start/end rituals

Core Concepts

1. Project Types

Code Projects

  • Live in your projects folder (e.g., ~/projects/)
  • Have git repositories
  • /hello pulls latest code
  • /bye handles commits and pushes
  • Example: Mobile apps, web apps, APIs, libraries

Documentation Projects

  • Live in your cloud sync folder
  • No git required
  • Great for non-code work
  • Example: Research, planning, writing, brainstorming

MVP/Startup Projects

  • Live in your projects folder (like code projects)
  • Enable "AI Co-Founder" mode with autonomous execution
  • Include decision frameworks, metrics tracking, and structured reviews
  • Claude operates more proactively: proposing solutions, executing independently within bounds
  • Example: Startups, MVPs, side projects where you want maximum AI leverage

2. Layered Documentation

Documentation exists at two levels:

Layer 1: Brief Summaries (Root)

  • Location: [docs_path]/SessionNotes/
  • Purpose: Quick overview of all work
  • Content: What projects, brief accomplishments, links to details
  • Format: One file per session date

Layer 2: Detailed Notes (Per Project)

  • Location: [project]/SessionNotes/
  • Purpose: Technical deep-dive
  • Content: Code changes, commits, decisions, blockers
  • Format: Multiple files per project, by topic

Why two layers?

  • Quick context: Scan root SessionNotes to see what happened recently
  • Deep dive: Read project SessionNotes only when needed
  • Efficient: Don't load unnecessary detail

3. CLAUDE-INSTRUCTIONS.md

Every project has a CLAUDE-INSTRUCTIONS.md file. This is the single source of truth for project context.

What it contains:

  • Setup instructions (how to run, dependencies)
  • Current status (what's working, what's not)
  • Next steps (priorities for upcoming work)
  • Notes & context (decisions, constraints, gotchas)
  • Last session info (date, summary)

Why it works:

  • Claude reads it at session start via /hello
  • Claude updates it at session end via /bye
  • Context persists without you re-explaining

4. Session Flow

START SESSION
    │
    ├─→ Run /hello
    │   ├─ List available projects
    │   ├─ User selects project
    │   ├─ Read CLAUDE-INSTRUCTIONS.md
    │   ├─ Pull latest code (if git)
    │   └─ Read NEXT-SESSION-START-HERE.md
    │
    ├─→ Work on project
    │   ├─ Make changes
    │   ├─ Create commits
    │   └─ Document decisions
    │
    └─→ Run /bye
        ├─ Create brief summary (root)
        ├─ Create detailed notes (project)
        ├─ Update CLAUDE-INSTRUCTIONS.md
        ├─ Handle git push (ask user)
        └─ Update NEXT-SESSION-START-HERE.md

5. NEXT-SESSION-START-HERE.md

This file answers: "Where do I pick up?"

Contains:

  • Current state (branch, commit, build status)
  • Last session summary with link to detailed notes
  • Next priorities in order
  • Blockers or waiting items

Updated by: /bye at the end of each session

6. Development Standards

The workflow includes a DEVELOPMENT-STANDARDS.md file that gets installed to ~/.claude/. This provides consistent guidelines for:

  • Code principles: DRY, YAGNI, SOLID, Clean Code
  • Git conventions: Commit message format, branching strategy
  • Code style: Formatting, linting, testing
  • Security: Secrets management, input validation
  • AI guidelines: How Claude should work with your code

Projects can reference these standards, and Claude will follow them when making changes.

7. Git Integration

For code projects, the workflow integrates with git:

On /hello:

  • Check if behind remote
  • Offer to pull latest

On /bye:

  • Show uncommitted changes
  • Offer to commit
  • Show unpushed commits
  • Offer to push
  • Document what was/wasn't pushed

Never automatic: The workflow always asks before git operations.

Design Principles

1. Never Lose Work

  • Session notes capture everything
  • Git status is always checked
  • Uncommitted work is documented

2. Easy to Resume

  • NEXT-SESSION-START-HERE.md provides quick context
  • CLAUDE-INSTRUCTIONS.md has full project state
  • Session notes have detailed history

3. Works Across Machines

  • Documentation syncs via cloud
  • Code syncs via git
  • Config is per-machine (paths can differ)

4. Minimal Friction

  • /hello and /bye are simple to type
  • Prompts have sensible defaults
  • Workflow adapts to your choices

5. Human-Readable

  • All files are markdown
  • Can browse/edit without Claude
  • History is preserved

When to Use This

Good fit:

  • Multiple projects you switch between
  • Long-running work over many sessions
  • Need to track decisions and progress
  • Work on multiple machines

Maybe overkill:

  • One-off quick tasks
  • Single project you never leave
  • Don't care about history