Claude Code First Prompt

Are you frustrated when AI Agents perform really noob? Losing contexts, losing track of current progress, most of the problems we face everyday will be solved using the following prompt. You can skip to the prompt below.

I think it's good to share this to people as well as my future self. We can update, refine, discuss this further.

For context, I'm a full stack developer so I have to work with multi repos workspace. I usually use Claude Code at the workspace's root so it will have all the contexts it need. but having a good system is important. It will guide the whole development process. So I wrote this system prompt. I hope it helps.

Use this prompt in a new workspace or repository to set up 3-level planning and tracking system. First level is just really high level, 1-3 sentences per actual task/feature/job. Second level is the plan of that, and last level is just all the detailed tasks on how to implement the plan.

Copy everything below the line and paste it as your first message.

I need you to set up a project management system for this workspace. Take your time — research carefully, read all existing docs, code, git history, and memory files before writing anything.

What to build

A 3-level hierarchical planning system:

1. Level 1 — ROADMAP.md (workspace root): A small table listing every epic (feature/bug/task) with its status and a link to its plan file. This is the ONLY file every conversation reads. Keep it under 50 lines.

2. Level 2+3 — plans/<epic>.md (one file per epic): Each file contains the plan (what/why/how) AND the detailed task checklist. Only the conversation working on that epic reads its file. Completed epics go to plans/_done/ (1-liner summaries, never read unless asked).

3. CLAUDE.md (workspace root): Instructions for every new conversation. Must include:

Start Here (navigation)

• Read ROADMAP.md → open the relevant plan file → implement

Mindset (behavioral rules)

• Plans are guides, not contracts — rewrite if research invalidates assumptions
• Stay skeptical — verify files exist, APIs work, code matches docs. Codebase is truth, not the plan
• When stuck or uncertain, ask the user
• Test-first — write tests before implementation, run tests before marking tasks done
• Clean commits — remove debugging artifacts, unused imports, dead code from failed approaches before committing

Unplanned work

• Small fix (< 5 min): just do it, no epic needed
• Medium+ task: create a new epic (ROADMAP row + plan file), then implement

Bookkeeping

• Update plan checkboxes as you complete tasks
• When epic is DONE, move plan to _done/ and update ROADMAP link
• Commit and push often

How to research

Before writing anything:
2. Read all memory files (if they exist)
3. Read any existing planning docs, task trackers, or roadmaps
4. Check git log for each project (recent 20 commits) to understand current state
5. Explore the codebase to understand what's implemented vs what's planned

How to categorize epics

• Completed work → status DONE, plan in plans/_done/ (1-liner)
• Active/upcoming work → status TODO, plan in plans/ (full plan + tasks)
• Identify features, bugs, cleanup tasks, and infrastructure work separately

What NOT to do

• Don't put everything in one file — the whole point is that conversations only load what they need
• Don't add generic coding rules the AI already knows ("write clean code", "use good names")
• Don't over-plan — if there are only 3 tasks, you don't need a plan file, just do it
• Don't skip the research phase — the plans must be grounded in real code, not assumptions

After creating the system

Walk me through what you created. Then stress-test it: think of 5+ failure scenarios and tell me if any rules are missing. Only add rules for specific failure modes you can identify, not hypothetical ones.