Skip to content

FAQ.md

Latest commit

 

History

History
167 lines (122 loc) · 4.65 KB

FAQ.md

File metadata and controls

167 lines (122 loc) · 4.65 KB
Raw

Frequently Asked Questions

Setup Questions

What cloud sync services work?

Any service that syncs a folder: Dropbox, pCloud, Google Drive, OneDrive, iCloud Drive, Syncthing, etc.

Can I use this without cloud sync?

Yes, but you'll lose the ability to access documentation across machines. Just use a local folder for docs_path.

Do I need git?

Only for code projects. Documentation-only projects don't require git.

What if I already have a projects folder?

Use your existing folder! The setup just needs to know where it is.

Can I change paths after setup?

Yes, edit ~/.claude-workflow/config.json with your new paths.

Usage Questions

What if I forget to run /bye?

No data is lost, but:

  • Session notes won't be created
  • CLAUDE-INSTRUCTIONS.md won't be updated
  • NEXT-SESSION-START-HERE.md won't be updated

Next session, you can:

  1. Update CLAUDE-INSTRUCTIONS.md manually
  2. Or just continue and run /bye when done

Can I work on multiple projects in one session?

Yes! /bye will:

  • Ask about each project you touched
  • Create notes for each
  • Update each project's CLAUDE-INSTRUCTIONS.md

What if /hello doesn't find my project?

Check that:

  1. The project folder exists
  2. It contains a CLAUDE-INSTRUCTIONS.md file
  3. It's in the right location (projects_path or docs_path/claude-projects)

Can I edit CLAUDE-INSTRUCTIONS.md manually?

Absolutely. It's just a markdown file. Edit it anytime.

What if I don't want to push my git commits?

Just say "no" when /bye asks. It will document the unpushed commits in your session notes.

File Questions

Where are session notes saved?

  • Brief notes: [docs_path]/SessionNotes/SESSION-YYYY-MM-DD.md
  • Detailed notes: [docs_path]/claude-projects/[project]/SessionNotes/SESSION-YYYY-MM-DD-TOPIC.md

What's the difference between brief and detailed notes?

  • Brief: High-level summary, covers all projects in one file
  • Detailed: Technical deep-dive, one file per project/topic

Can I delete old session notes?

Yes. They're just documentation. Archive or delete as you see fit.

Where is the config stored?

~/.claude-workflow/config.json

Where are the commands stored?

~/.claude/commands/ (hello.md and bye.md)

Troubleshooting

Commands not working after install

  1. Restart Claude Code
  2. Check files exist in ~/.claude/commands/
  3. Check file permissions

"Config not found" error

Create ~/.claude-workflow/config.json:

{
  "projects_path": "/path/to/your/projects",
  "docs_path": "/path/to/your/cloud/Claude"
}

Session notes not syncing

  1. Check your docs_path is inside a synced folder
  2. Verify your cloud sync app is running
  3. Check for sync errors in your cloud app

Git operations failing

  1. Make sure you're in a git repository
  2. Check you have remote configured (git remote -v)
  3. Check you have push access

Project not showing in /hello

  1. Verify CLAUDE-INSTRUCTIONS.md exists in the project folder
  2. Check the project is in the right location
  3. Check config.json has correct paths

Customization

Can I modify the commands?

Yes! The files in ~/.claude/commands/ are just markdown. Edit them to change behavior.

Can I add more commands?

Yes. Create additional .md files in ~/.claude/commands/. They'll be available as /filename.

Can I change the templates?

Yes. Copy templates to your projects and modify as needed.

Can I use different file names?

The workflow expects:

  • CLAUDE-INSTRUCTIONS.md for project context
  • SessionNotes/ for notes
  • NEXT-SESSION-START-HERE.md for quick resume

You can modify the commands to use different names, but these are the defaults.

Migration

I have existing projects - how do I add them?

  1. Create CLAUDE-INSTRUCTIONS.md in each project (use templates)
  2. Fill in current status and next steps
  3. They'll appear in /hello

Can I use this with an existing notes system?

Yes. You can:

  • Use your existing folder as docs_path
  • Customize where notes are saved
  • Link to your existing notes in CLAUDE-INSTRUCTIONS.md

Moving from another workflow system?

  1. Set up this workflow
  2. Import relevant info into CLAUDE-INSTRUCTIONS.md files
  3. Old system can coexist or be archived

Philosophy

Why not just tell Claude the context each time?

You can! But:

  • It's repetitive
  • You might forget important details
  • No history of decisions
  • Hard to resume after breaks

Why layered documentation?

Efficiency:

  • Brief notes for quick scanning
  • Detailed notes only when needed
  • Less cognitive load

Why update files at session end?

  • Fresh context for next session
  • Documentation while details are fresh
  • Clear stopping point