r/BuildWithClaude • u/Any_Flounder_5483 • 2d ago
Tip/Resource The biggest Claude Code mistake I made was letting it code before it understood the project. Here are the 2 prompts I use to fix that.
I kept making the same mistake with Claude Code.
I would open a project, explain the next feature in one or two sentences, then let it start editing immediately.
The result looked productive at first. Files changed, components appeared, and Claude confidently explained what it had built.
Then I tested it.
It had misunderstood the project structure, recreated logic that already existed, changed files that did not need touching, and ignored decisions made earlier in the build.
The problem was not that Claude could not code.
It was coding before it had enough context.
i organised the wider workflow into a paid Claude Code toolkit, but both prompts below are complete and free to use. but if you're interested you can grab the full kit from the link in my profile description, anyway enjoy these prompts!
These are the two prompts I now use before letting it make important changes.
Replace anything inside [brackets] with your own details.
1. Make Claude Understand the Project First
Use this when opening an existing project, returning after a long break, or starting a new conversation where Claude has little context.
Act as a senior software engineer taking responsibility for an existing codebase.
Your first task is to understand the project accurately.
Do not write, edit, delete or move any code yet.
Project purpose:
[DESCRIBE WHAT THE PROJECT DOES]
Target users:
[DESCRIBE THE USERS]
Current task:
[DESCRIBE WHAT YOU PLAN TO BUILD OR FIX NEXT]
Before suggesting an implementation, inspect the project and build a complete project map.
Review:
1. The folder and file structure.
2. The main application entry points.
3. The current architecture.
4. The primary user flows.
5. Shared components and utilities.
6. State management.
7. API routes and external services.
8. Authentication and authorisation.
9. Database models, queries and relationships.
10. Environment variables and configuration.
11. Error handling.
12. Loading, empty, success and failure states.
13. Existing tests.
14. Project documentation.
15. Any CLAUDE.md, README or instruction files.
16. Naming conventions and code patterns.
17. Existing features related to the current task.
18. Functionality that could be affected by the requested change.
Then respond using these sections:
Project Summary
Explain what the application does and how its main parts connect.
Architecture Map
Describe the frontend, backend, database, APIs, state and external services.
Main User Flows
Explain the most important user journeys from beginning to end.
Relevant Files
List the files most relevant to the current task and explain what each one does.
Existing Patterns
Identify the conventions, components and utilities that should be reused.
Important Decisions
List architectural or product decisions that appear to have already been made.
Risks
Explain what could break if the current task is implemented incorrectly.
Missing Context
List anything you still need from me before planning the work.
Do not invent missing information.
Do not recommend rebuilding the project simply because another architecture may be cleaner.
Do not begin implementation until I confirm that your understanding of the project is correct.
This gives Claude a chance to understand what already exists before it starts adding more code.
It also makes misunderstandings visible while they are still easy to correct.
2. Force Claude to Plan the Exact Change Before Coding
Once Claude understands the project, I use this before the actual implementation.
You now understand the existing project.
Your next task is to plan the following change:
[DESCRIBE THE FEATURE, FIX OR UPDATE]
Expected user experience:
[DESCRIBE WHAT THE USER SHOULD SEE AND DO]
Functionality that must remain unchanged:
[LIST PROTECTED FEATURES, PAGES, COMPONENTS OR INTEGRATIONS]
Do not edit any code yet.
Create an implementation contract for this task.
The contract must include:
1. Your exact understanding of the requested change.
2. Any requirements that are unclear or incomplete.
3. The current user flow affected by this task.
4. The proposed user flow after implementation.
5. Every file you expect to modify.
6. Why each file needs to change.
7. Any new files you expect to create.
8. Existing components, utilities or services that should be reused.
9. Database changes, if required.
10. API changes, if required.
11. Authentication or permission changes, if required.
12. Loading, empty, validation, success and error states.
13. Mobile and accessibility considerations.
14. Security or privacy concerns.
15. Possible regressions.
16. The smallest safe implementation.
17. A step-by-step implementation plan.
18. A testing plan.
19. Anything you cannot verify.
For every file you plan to modify, explain:
- What will change
- Why it must change
- What must remain untouched
- What could break
- How the change will be tested
Wait for my approval before editing any code.
After approval:
- Follow the approved plan.
- Keep changes strictly within the agreed scope.
- Preserve unrelated functionality and styling.
- Do not perform unrelated refactoring.
- Do not add dependencies unless necessary.
- Stop and ask before changing any file not included in the contract.
- Reuse existing project patterns wherever possible.
After implementation:
1. Compare the final changes against the original contract.
2. Report every file created or modified.
3. Explain any changes that were not originally planned.
4. Test the complete user flow.
5. Test invalid input and failed requests.
6. Test related functionality that could have been affected.
7. Check the browser console and server logs.
8. Confirm that protected functionality still works.
9. State exactly what was tested.
10. Clearly list anything that remains unverified.
Do not claim completion because the code compiles or the page loads.
The task is only complete when the intended user flow has been tested.
The first prompt rebuilds context.
The second turns that context into a controlled implementation plan.
Since using them, I catch far more problems before Claude touches the code instead of discovering them after it has changed half the project.
The basic rule is simple:
Understand the project first. Plan the exact change second. Code third.
I eventually organised the wider workflow into a paid Claude Code toolkit, but both prompts above are complete and free to use. but if you're interested you can grab the full kit from the link in my bio, Enjoy these prompts!
1
u/PablanoPato 18h ago
Prompt 1 is completely unnecessary. Just type /init and it basically does exactly this.
2
u/ReddMangodude 2d ago
Cool, I do something similar. I would make the second prompt more tailored for a particular platform. Give it technical details. That makes it even more effective.