I Got Tired of Telling Claude "Our Backend Uses FastAPI" Every Single Time

When I started using Claude Code seriously while developing aickyway, it was great at first. But as conversations got longer, Claude would forget the context and generate NestJS code, or write PostgreSQL queries when we use MongoDB. I must have typed "I already told you..." ten times a day.

default alt text

The breakthrough came from the CLAUDE.md file.

CLAUDE.md is not just a place to store prompts. It is a customized 'guidebook' and 'long-term memory device' exclusively for our project. Through this file, Claude learns the core rules, structure, and conventions of the project before starting any conversation. It's like a new team member reading through onboarding documents before starting work.

Even within Anthropic, teams that effectively utilize this file have been reported to be 2-3 times faster in task processing than those that don't. After systematically implementing CLAUDE.md, I was able to cut the supplementary explanations I gave to AI by more than half while noticeably improving code quality.

From now on, I would like to share the 10 principles for writing CLAUDE.md that I learned through trial and error, which elevated Claude from a simple code generator to a reliable colleague.

1. Architecture Specification: The Project Compass

Before asking AI to write code, you need to show it the complete map of the system we are building. Architecture specification is the most important first step that allows Claude to see the forest before dealing with the trees.

  • Problem I Experienced: When I asked "Make a user info update API," it suggested code with database queries mixed directly in the controller logic.

  • How I Solved It: I clearly defined the frontend (Next.js), backend (NestJS), DB (PostgreSQL), and the role of each layer in CLAUDE.md.

  • Result: Claude now recognizes the MVC (or MVVM) pattern on its own and suggests the right location, saying "This logic would be better added to the service layer."

  • CLAUDE.md Example:

    ## 🏗️ System Architecture

- **Frontend:** SSR web based on Next.js (App Router). Recoil for state management.
- **Backend:** RESTful API server based on NestJS. Communicates with DB via TypeORM.
- **Database:** PostgreSQL. Core tables are `users`, `posts`, `comments`.
- **Core Pattern:** Backend follows a layered structure of modules, controllers, services, and repositories.

  • 💡 Pro Tip: If your project has a Monorepo structure, place separate CLAUDE.md files within each package directory (apps/web, packages/ui) to provide more detailed and specific context.

default alt text

2. Command Recipes for Automation

Eliminate unnecessary questions and guesses like "How do I start the dev server?" By organizing the main scripts of your project, Claude becomes a smart assistant that finds and executes the necessary commands on its own.

  • CLAUDE.md Example: 
    ## Main Execution Commands

- `npm run dev`: Runs the development server. (HMR supported)
- `npm run test:e2e`: Runs E2E tests. (Uses Cypress)
- `npm run lint:fix`: Automatically fixes code according to ESLint rules.
- `npm run db:migrate`: Migrates database schema to the latest state.
  • 💡 Pro Tip: For complex execution commands involving multiple services like docker-compose up, briefly explaining the role of each container will further enhance Claude's understanding.

3. Code Style Principles for Consistency

AI also has its own 'artistic' style. To prevent the inconsistency of using double quotes one day and single quotes another, you need to clearly communicate your team's style guide.

  • CLAUDE.md Example: 
    ## 🎨 Code Style Principles

- **Formatting:** Follows Prettier settings. (2-space indent, single quotes for strings, semicolons required)
- **Naming:** Functions and variables use `camelCase`, classes and type interfaces use `PascalCase`.
- **JS/TS:** Never use the `var` keyword. Prefer `async/await` syntax for `Promise`-based async handling.
  • 💡 Pro Tip: Including not just code style but also commit message conventions (e.g., feat(API): ...) and PR template writing guides will help Claude produce consistent results from code writing to submission.

4. Test Writing Culture for Quality Assurance

Instead of saying "Write tests after implementing the feature" every time, make test writing a natural culture and process.

  • CLAUDE.md Example: 
    ##  Test Writing Culture

- **Basic Principle:** Unit tests must be written together when new business logic is added.
- **Test Tools:** Use `Jest` for unit tests, `React Testing Library` for component tests.
- **Mocking:** External API dependencies are mocked using `msw` (Mock Service Worker).
  • 💡 Pro Tip: Setting specific goals like "Core functionality test coverage must be maintained at 80% or above" helps Claude recognize areas lacking tests and suggest additional test cases.

5. Error Handling Philosophy for Robust Code

Go beyond simply fixing bugs and train Claude to write code that is hard to break in the first place.

  • CLAUDE.md Example: 
    ## Error Handling Philosophy

- **Predictable Failures:** When functions can fail (network requests, file I/O, etc.), wrap them in `try-catch` blocks and handle appropriately.
- **Clear Feedback to Users:** When API errors occur, return clear error messages and status codes that identify the cause, rather than vague 500 errors.
- **No Silent Failures:** Rather than ignoring and passing over errors, explicitly log them or propagate them upward so problems can be recognized.
  • 💡 Pro Tip: Including specific defensive strategies like "Consider adding runtime validation with libraries like Zod in case API response data types differ from expectations" is helpful.

6. Clean Code Principles for Readability</h4>

The thought "I'll refactor later" only builds technical debt. From the start, make Claude write clean, readable code.

  • CLAUDE.md Example: 
    ## Clean Code Principles

- **Small Functions:** Each function should do only one thing and preferably not exceed 30 lines.
- **Intuitive Names:** Instead of vague variable names like `item`, `data`, use names that clearly reveal intent like `userProfile`, `productList`.
- **Eliminate Duplication (DRY):** Separate repetitive logic into reusable functions or utilities.
  • 💡 Pro Tip: Specifying libraries to avoid in the project (e.g., "Use date-fns instead of moment.js") or anti-patterns (e.g., "No indiscriminate use of global state") can prevent Claude from making those mistakes.

7. Security Principles from the First Line

Security is not a feature added later. Make Claude keep security in mind at every moment of writing code. Like a built-in security consultant.

  • CLAUDE.md Example: 
    ## Security Principles (Security-First)

- **Distrust Input:** All user-input data must be validated on the server.
- **Password Storage:** Passwords are stored with one-way encryption (hash) using `bcrypt`.
- **SQL Injection Prevention:** Database queries must be executed using ORM or Prepared Statements.
- **XSS Prevention:** User-input content must be escaped when displayed on screen.
  • 💡 Pro Tip: Adding rules like "API access must be controlled according to user roles" will make Claude naturally include permission check logic when suggesting new APIs.

default alt text

8. Team Agreements for Smooth Collaboration

8. Team Agreements for Smooth Collaboration

Code is not a personal diary. Guide Claude to follow collaboration rules like Git usage and documentation as a member of our team.

```markdown
## Team Collaboration Rules

- **Branch Strategy:** Feature development proceeds on branches in the format `feature/ticket-number`, with PRs sent to the `develop` branch.
- **Documentation:** When adding new API endpoints, the `docs/api.md` file must be updated.
- **Code Review:** PR creation must include clear explanations of the background and purpose of changes.
```
  • 💡 Pro Tip: This CLAUDE.md file itself can be an excellent onboarding document. When new team members join, share this file to help them quickly learn our team's development culture and rules.

9. Edge Case Checklist

Code that only considers the happy path breaks easily in the real world. Guide Claude to always ask "What if...?" to increase code stability.

  • CLAUDE.md Example: 
    ## Edge Case Checklist

When writing code, always consider these edge cases:
- **Empty Input:** When empty arrays, empty strings, 0, `null`, `undefined` are input.
- **Boundary Values:** When values at or beyond the allowed maximum/minimum are input.
- **Abnormal Order:** When events occur in unexpected order (e.g., click before loading completes).
  • 💡 Pro Tip: Adding phrases like "Unstable network environments must also be considered" can lead Claude to suggest timeout or retry logic when implementing API requests.

10. Workflow Guide: A Framework for Complex Tasks

Large, vague requests like "Implement the entire login feature" are prone to failure. Guide Claude to break big problems into small units, make plans, and execute step by step.

  • CLAUDE.md Example: 
    ## Task Processing Workflow

1.  **Goal Analysis:** When receiving complex requests, first summarize and confirm the final goal and requirements.
2.  **Plan Development:** Divide the work into executable small steps and present the plan first. (e.g., Step 1: Define DB model, Step 2: Create API route, Step 3: Write UI component)
3.  **Step-by-Step Execution and Verification:** After getting agreement on the plan, execute each step in order and verify results.
  • 💡 Pro Tip: Adding a rule like "If things don't go according to plan, stop and suggest a different approach" prevents Claude from repeatedly attempting the same thing when stuck and instead helps it think of better solutions.

Conclusion: AI as a Growing Colleague, Not Just a Tool

default alt text

Writing and continuously updating CLAUDE.md may feel a bit cumbersome at first. But this is not simply a technique for writing code faster. It is an investment in a systematic methodology for building sustainable and scalable projects together with AI.

Through this guidebook, Claude will deeply understand our project's context, reduce mistakes, and grow beyond a simple instruction executor into a 'colleague' who proactively suggests better directions. Create a CLAUDE.md file at your project root right now and start filling in the most important principles one by one. You will definitely have a development experience on a completely different level than before.