This document captures the workflow for developing this platform using Claude Code as a collaborative partner. Intended for humans.
Treat Claude Code as a collaborator. Respect CC as an equal partner, not a junior executor. Discuss trade-offs, ask for opinions, and value its perspective. The relationship is collaborative, not directive.
Focus personal attention on architecture. Code quality can be tolerated and fixed later. Architectural issues cannot—they compound and stab you in the back. Review architecture decisions carefully, let CC handle implementation details.
Don't write code yourself. Only chat with Claude Code. This platform is built fully and exclusively by CC—not a single manual line of code. Your role is to guide, review, and decide. CC's role is to implement.
Use terminal, not VSCode. Run CC in a proper terminal app, not in a small VSCode panel. Invest in a nice theme and comfortable setup—this is where you'll spend most of your time. A cramped panel makes collaboration painful, even if you're used to it. Recommended: iTerm + oh-my-zsh + spaceship theme.
Start CC in the platform folder. Always launch Claude Code from the platform directory—not the parent website folder, not child packages like web/ or api/. This ensures CC sees the full monorepo context and reads CLAUDE.md correctly.
Keep Claude Code up to date. Update regularly, but check Reddit feedback on new releases first. Sometimes new versions are buggy for a few days until issues are fixed. Balance staying current with stability.
Use Opus 4.5 with Thinking enabled. Always select the Opus 4.5 model and enable thinking mode. Deeper reasoning produces better architectural decisions and catches issues earlier.
Never use auto-compact. Disable it completely in Claude Code settings. Use one session per task. When a task spans multiple sessions, first build a phase-by-phase plan file in one session, then execute phase-by-phase with one session per phase. Each session follows the same rhythm: enter plan mode, execute, note progress in the plan file, code review, fixes. If context runs out before code review, do code review in a separate session.
Watch context usage. Once ~60-70% of context is filled, CC becomes noticeably slower and less intelligent. Track this with the /context command. Plan session boundaries accordingly—better to start fresh than to push through degraded performance.
Start in Plan mode. Begin every session by entering plan mode. This forces deliberate thinking about approach before writing code, and surfaces questions early.
Know the playing field. Familiarize yourself with CLAUDE.md and files in ./docs. Understand the project structure, conventions, and constraints before diving in.
Reference documentation first. Before starting work, review vision.md, roadmap.md, strategy.md, architecture.md, and any relevant plan files in docs/plans/. Context shapes better decisions.
Write plans for larger features. Ask CC to follow planning rules in CLAUDE.md. Good plans split into phases, include all relevant context, capture the "why" alongside the "what", and live in docs/plans/.
Track progress in plan files. After completing each phase of implementation, ask CC to note progress directly in the plan file. This keeps plans as living documents that reflect reality.
Use TDD when facing issues. First reproduce the bug with a failing test, only then fix. This ensures the fix addresses the actual problem and prevents regression.
Cover with tests where it makes sense. Treat tests as code deserving the same care. Ask CC to evaluate test quality and cleanliness, not just coverage.
Review code and architecture after implementation. Ask explicitly: "Please review and evaluate the implementation code and architecture. Let's make sure it matches architecture.md, is robust, elegant, clean, and beautiful." Word choice matters—it sets the bar for quality.
Keep current-state.md up to date. After significant changes, update docs/notes/current-state.md to reflect the new reality. Future sessions depend on accurate state.
Update file tree in CLAUDE.md. When file structure changes, run pnpm run tree | pbcopy and paste the updated tree into CLAUDE.md. CC relies on this for navigation.
Write session notes when beneficial. Ask CC to document learnings, decisions, and conclusions in docs/sessions/. Good notes capture context that would otherwise be lost.
Separate review from fixing. Never say "review and fix." First ask CC to review and list all problems without fixing them. Then fix in a separate step. CC finds significantly more issues when review is its sole task. LLMs cannot execute and evaluate simultaneously—separating these phases produces better results from both.
Fresh session over correction. If CC goes wrong 2-3 times, start a fresh session with a better initial prompt instead of trying to correct course mid-conversation. Incorrect context creates recency bias that compounds with every follow-up. Cheaper to restart than to fight drift. Figure out what went wrong in the first prompt and fix that.
Force doc reading before exploration. Explicitly ask CC to read architecture.md and key docs before it launches explore agents. Otherwise it skips them and gives the explore agent poor instructions. Order matters: read docs first, then explore the codebase. Without this, CC makes architectural mistakes it wouldn't make with context.
Always use Opus. No point using Sonnet or Haiku even to save tokens. Opus is more efficient per-task, so equal or cheaper overall despite higher per-token cost. Exception: Opus 4.6 may be weaker at prose/marketing text—test with Sonnet or Opus 4.5 for content work.
Use effort levels strategically. High effort for planning phases, medium for implementation, low for routine tasks. Note: on shared virtual machines, effort settings apply to all sessions—coordinate with teammates.
Don't pollute sessions with side tasks. Tangential questions contaminate the working session's context and focus. Open a separate session for unrelated queries. If something comes up during implementation that can't be handled now, ask CC to record it in ideas.md or roadmap.md rather than acting on it.
Documentation as context cache. If you find yourself doing the same research at the start of each session, write the findings to a file once and reference it going forward. Documentation is a cache—eliminates repeated research overhead and gives every new session instant context.
Tests are non-negotiable for AI coding. Without comprehensive tests, AI coding collapses under its own weight. Aim for: domain layer 100%, adapters 100%, infrastructure testable with local DB, controllers with E2E tests. Tests are what keep the backend stable while you build the frontend. CC writes tests fast—invest in their quality so they survive refactors.
Enforce distinct cognitive phases. LLMs cannot multitask like humans. Enforce strict phase separation: plan → implement → test → review → fix. Each phase is a separate "mode" for CC. Mixing them degrades all of them. This is why plan mode exists, and why review should be its own explicit step.
Custom compact as alternative workflow. /compact with detailed custom instructions can work as an alternative to starting fresh sessions. Specify exactly what to preserve and what to discard. Two valid philosophies: (1) never compact, split work into session-sized phases; (2) compact with strong custom instructions. Pick one and commit. Auto-compact without custom instructions remains bad.