Designing a project from scratch
Working with Claude on Projects
The previous seven chapters covered the components of a well-designed Claude Code project: CLAUDE.md, memory files, shorthand prompts, multi-session workflows, slash commands, skills, and MCP servers. This final chapter brings them together — a practical walkthrough of setting up a new project from zero, with every decision explained. The worked example is this course itself.
Before You Open Claude — Three Questions
Project design starts before any file is created. Three questions determine most of the architecture:
| Question | What it determines |
|---|---|
| 1. How long will this project run? | A one-day project doesn't need a memory system. A multi-month project needs it from day one — retrofitting memory into a mature project is painful. |
| 2. How much does Claude need to know to start each session usefully? | If the answer is "a lot," invest in CLAUDE.md and rich memory files. If the answer is "just the current task," a minimal setup is fine. |
| 3. What recurring workflows will you perform many times? | Identifies candidates for shorthand prompts or skills. If you can name the recurring actions in advance, build the shorthand map before the first session. |
For this project — a learning website with dozens of courses, each with 8–12 chapters, spanning months of work — the answers were: long-running, high context requirement, and highly repetitive workflows (chapter generation, SQL, PDF). All three pointed to a structured project setup from the start.
Phase 1 — Write CLAUDE.md
CLAUDE.md loads at the start of every session. It should answer the questions Claude would otherwise ask in the first few turns. For this project it contains:
- Project overview — what the website is, who it's for, the URL
- Tech stack — PHP/HTML/CSS, dark theme, specific colour values per course category
- File conventions — all generated files go in
claude-generated-files/, fragment HTML only (no DOCTYPE), naming patterns - Recurring workflows — chapter generation, SQL insert scripts, PDF builds. The existence of the shorthand system is noted so Claude knows to check memory before asking.
- Hard rules — always use vim not nano, commit message style, never force-push
What it does not contain: every course outline, every chapter list, every style value. Those live in memory files, which are loaded on demand — CLAUDE.md stays short so it loads fast and doesn't crowd out context.
One paragraph: what this is, who uses it, the goal.
## Tech Stack
- Language / framework
- Key libraries or tools
- Deployment target
## File Conventions
- Where generated files go
- Naming patterns
- What format (fragment HTML / full page / etc)
## Recurring Workflows
- Shorthand prompts: see memory/[course]_course.md
- SQL: see memory/learning_blog_sql.md
- PDF: always build at end of final chapter
## Hard Rules
- Use vim, never nano
- [Any other non-negotiables]
Phase 2 — Design the Memory Structure
Plan which memory types you'll use before starting, then create the files as information arrives — not all at once upfront.
- User memory — one file, updated rarely. Role, background, preferences that affect how Claude writes and explains things.
- Feedback memory — one file per rule or cluster of rules. Add entries after every correction or confirmation worth keeping. These are the highest-ROI memories.
- Project memory — one file per course or major workstream. Contains the outline, status table, naming conventions, and next step. Updated at the end of each session.
- Reference memory — one file per external system that Claude needs to query or interact with. Database schema, API locations, SQL insert conventions.
Keep MEMORY.md hooks under ~150 characters each — the index must stay skimmable so Claude can select the right files quickly. If a hook is getting long, the memory file it points to needs splitting.
The shorthand prompt map — a special case of project memory
For any project with repetitive workflows, the shorthand map is the most valuable memory file you'll write. Design it before the first session if you can, or extract it from CLAUDE.md as patterns emerge. This project's map maps short codes like vpn6 or proj3 to: file to create, styling spec, content outline, and what to do at the end. One memory file eliminates dozens of repeated instructions per course.
Phase 3 — Decide on MCP Servers and Skills
Don't connect every available MCP server on day one. Start with what you know you need. This project started with just the built-in filesystem and shell servers, then added computer use and the Chrome extension as browser testing became relevant.
- MCP servers: connect a server when a real task needs it, not speculatively. "We might want to query the database directly someday" is not a reason to set up the postgres server today.
- Skills: prototype a workflow in chat for two or three sessions. Once the prompt is stable and you're typing it repeatedly, extract it into a skill file. This project's session-diary skill came from a manually-typed prompt that worked well in three consecutive sessions before being formalised.
Phase 4 — The First Session
The first session of a new project is an investment, not a sprint. Spend it on:
- Verifying that Claude has read CLAUDE.md correctly — ask it to summarise the project from the file
- Doing one real task so you can observe what Claude gets wrong or assumes incorrectly
- Saving the first round of feedback memories from those observations before closing
- Writing the shorthand map memory file if you didn't already
The payoff arrives in session two: Claude starts with the right context, makes fewer wrong assumptions, and the first task completes faster than it would have in session one.
Maintaining the Project Over Time
A project that runs for months needs maintenance:
- Review CLAUDE.md quarterly — remove sections that no longer apply, update the tech stack if it's changed, trim anything that's migrated to memory files
- Consolidate memory every few weeks — merge duplicates, remove stale entries, check that MEMORY.md hooks still accurately describe their files
- Retire completed workstreams — a course that's finished shouldn't still have an active project memory file with a "next step" entry. Archive it or mark it clearly as complete.
- Update skills when workflows evolve — a skill that generates the wrong format because the target changed will silently produce wrong output. Review skills when the underlying workflow changes.
Project Design Checklist
Before the first session
- ✓Answered the three framing questions (duration, context need, recurring workflows)
- ✓Written a CLAUDE.md with project overview, tech stack, file conventions, and hard rules
- ✓Planned memory file structure (which types, one file per workstream)
- ✓Created MEMORY.md index (even if mostly empty — the structure matters)
- ✓Identified recurring workflows and sketched the shorthand map
End of every session
- ✓Decisions made this session are saved to the relevant memory file
- ✓Status tables in course memory files updated to reflect what was completed
- ✓"Next step" note written to the project memory file
- ✓Any new feedback (corrections or confirmations) saved to feedback memory
- ✓Generated files confirmed written to disk before closing
Periodic maintenance
- ✓CLAUDE.md reviewed and trimmed — no stale sections
- ✓Memory consolidated — no duplicates, no stale references
- ✓Completed workstreams archived or clearly marked done
- ✓Skills reviewed against current workflows