← Back to context

Comment by bonsai_spool

3 days ago

Are you seeing a benefit above doing this in the prompt / project structure?

Currently, I have Claude set up a directory with CLAUDE.md, a roadmap, a frequently used commands guide, detailed by-phase plans, and a session log with per-session insights and next steps.

After each phase is done, I have it update the documents and ask what could have been done to make the session easier—often the answer is clearer instructions, which eventually leads to topic-specific documents or a new Claude Skill.

(edit) These reflection tasks are spelled out in the CLAUDE.md and in the docs directory, so I don't have to type them. Each new session, I paste a guide for how Claude should access the information from the last session.

6 comments

bonsai_spool

Reply
joostdevries  3 days ago

I keep the context concise by linking from claude.md to markdown files with the hardware architecture, the network architecture, the processing tech stack. Concise and specific. And a current project md. I mix in the parts that are relevant. I don't have a roadmap and session log though. Good idea.

Bayram  3 days ago

Your workflow sounds solid - and honestly more disciplined than most. The difference I was going for: catching implicit corrections you don't consciously document.

So probably complementary to what you're doing, not a replacement. If you're already doing post-phase reviews, you might catch most of this anyway.

stefanfisk  3 days ago

I totally understand that this is not really a small ask, but if you could put together some sort of example repo of this setup I and probably a lot of people with me would be most grateful! I don't mean with running code or anything, just the doc structure for Claude.

  • bonsai_spool  3 days ago

    No problem! I recommend asking Claude for these sorts of things so they can better match your own processes.

    ----

    New session:

         ## Prompt
     
     Set up project documentation structure for this new project.
     
     Create the following:
     
     1. \*CLAUDE.md\* (project root) - Concise (<40 lines) entry point with:
         - One-line hypothesis/goal
         - "Start Here" pointing to docs/ROADMAP.md
         - Quick Reference (key commands)
         - Key Files table
         - Documentation links
         - "End of Session" protocol (append to docs/session_log.md)
     
     2. \*docs/ROADMAP.md\* - Status dashboard:
         - Current state table (what exists)
         - Blockers table (with links to plans)
         - Priority actions table (with links to plans)
         - Success criteria (minimum + publishable)
     
     3. \*docs/plans/\* directory with plan templates:
         - Each plan: Priority, Status, Depends on, Problem, Goal, Steps, Success Criteria
         - Name format: plan_descriptive_name.md (not numbered)
     
     4. \*docs/runbook.md\* - Common operations:
         - How to add new data sources
         - How to run analysis
         - How to run tests
     
     5. \*docs/session_log.md\* - Work history:
         - Template for session entries
         - "Prior Sessions" section for context
     
     6. \*docs/archive/\* - For completed/old docs
     
     If this is a data pipeline project, also set up:
      - SQLAlchemy + Pydantic architecture (see sqlalchemy_pydantic_template.zip)
      - tests/ directory with pytest structure
     - you can copy the file from ./generic_claude_project_src.zip to the current folder and unzip the copy. DO NOT modify the original file or try to move the original file
     
     Keep all docs concise. Link between docs rather than duplicating.
     
     ---
     
     ## After Setup Checklist
     
     - [ ] CLAUDE.md is <50 lines
      - [ ] ROADMAP.md fits on one screen
      - [ ] Each plan has clear success criteria
      - [ ] runbook.md has actual commands (not placeholders)
      - [ ] session_log.md has first entry from setup session
     
     ---
     
     ## python
     
     use the py-PROJECT pyenv
     
     ensure pyenv is installed
     
     ## Example Structure
     
     project/
      ├── CLAUDE.md                    # Entry point (<50 lines)
      ├── docs/
      │   ├── ROADMAP.md              # Status + plan links
      │   ├── runbook.md              # Common operations
      │   ├── session_log.md          # Work history
      │   ├── plans/
      │   │   ├── plan_data_loading.md
      │   │   ├── plan_analysis.md
      │   │   └── plan_validation.md
      │   └── archive/
      │       └── plans/              # Old plans with date prefix
      ├── src/ or project_name_src/   # Code
      └── tests/
          └── test_*.py
     
     ## Session log example
     
     ## YYYY-MM-DD: Brief Title
       \*Goal\*: What you aimed to do
     
       **Done**: What was accomplished (be specific)
     
       **Discovered**: Non-obvious findings about codebase/data/tools
     
       **Decisions**: Choices made and brief rationale
     
       **Deferred**: Work skipped and why (not just "next steps")
     
       **Blockers**: Issues preventing progress (or "None")
     
       The key shift: less about tasks completed, more about knowledge gained that isn't captured elsewhere.

    Continuation prompt

         Review the project state and tell me what to work on:
       1. Read docs/ROADMAP.md
       2. Read docs/session_log.md (last entry)
       3. Read the highest-priority plan in docs/plans/
     
       Then summarize:
       - Last session (1 line)
       - Current blockers
       - Recommended next step
     
       Ask if I'm ready to proceed.

    The zip archive above is just a standard Python module with __init__ and hints at how I'd like things to be named.