Maximizing AI Coding Assistants with CLAUDE.md

This is the first in a series about maximizing Claude Code productivity at the organizational level. It starts with CLAUDE.md design and its effects, then progresses to optimization through a skills system, automation with meta-skills, and planning team-wide deployment.

The Problem: AI Assistants Lack Project Context

Ever wondered why Claude Code or GitHub Copilot sometimes generates code that feels completely off? In my Next.js blog, Claude Code would frequently suggest patterns that didn't match our project conventions. It would propose Tailwind CSS v3 syntax when we're using v4, or try to read files directly instead of understanding our Velite content structure.

The root issue is that AI lacks project-specific context. README files are written for human users and don't contain the technical details or coding conventions that AI needs. That's why I introduced CLAUDE.md — a dedicated guideline file that helps Claude Code understand repository context and generate code that follows project conventions.

CLAUDE.md Structure and Design Philosophy

Note: This post presents the detailed CLAUDE.md (355 lines) I initially created, but this level of detail later proved counterproductive. Because CLAUDE.md is loaded into the context window at the start of every session, a bloated file causes Claude to miss important instructions. Part 2 covers how I solved this with a skills system, reducing it to just 59 lines. Keeping CLAUDE.md "short and limited to what's truly necessary" is a principle recommended by the official best practices.

CLAUDE.md isn't just documentation — it's an interface designed to optimize collaboration with AI. I structured it into five sections, ensuring AI can quickly access the information it needs.

1. Quick Reference — Immediately Needed Information

## Quick Reference
 
### Commands
```bash
npm run dev          # Dev server (http://localhost:3000)
npm run build        # Production build (next build --turbopack)
npm start            # Start production server
npm run lint         # ESLint + Prettier check
npm test             # Unit/component tests (Vitest)
npm run test:e2e     # E2E tests (Playwright, requires build)
```
 
### Code Change Checklist
When modifying code, complete these steps in order:
1. **Run tests if applicable:**
   - `src/lib/` or `src/components/` changes → `npm test`
   - Routing, pages, or i18n changes → `npm run test:e2e`

The first section contains information AI references frequently: command list and mandatory code change checklist. This enables Claude Code to instantly provide accurate answers to basic questions like "What's the build command?" or "How do I run tests?"

2. Architecture — System Overview

In the architecture section, I used tables and flow diagrams for visual clarity.

### Tech Stack
 
| Layer | Technology | Purpose |
|-------|------------|---------|
| **Framework** | Next.js 16 (App Router) | React framework with SSG support |
| **Content** | Velite + MDX | Static content generation from Markdown |
| **Styling** | Tailwind CSS v4 | Utility-first CSS with theme tokens |
| **i18n** | Custom implementation | TypeScript dictionaries, no external lib |

The Content Pipeline explanation is particularly important. It clearly shows how Velite processes MDX files and how Next.js consumes them, using directory structure and flow diagrams. This enables Claude Code to properly create MDX files in the right directory with correct frontmatter when asked to "add a new blog post."

3. Testing — Clear Test Strategy

### Test Conventions
 
- Mock `#site/content` → `__tests__/__mocks__/velite.ts`
- New functions in `src/lib/` → add tests in `__tests__/lib/`
- Component changes → add tests in `__tests__/components/<subdirectory>/`
- Page/routing changes → add E2E tests in `e2e/`

The testing section clearly defines which changes require which tests. This helps Claude Code generate appropriate tests alongside new features.

4. Content Writing — Integrated Style Guide

One of this blog's key features is its detailed content style guide. CLAUDE.md includes writing guidelines for blog posts and TIL entries with concrete examples.

### Blog Posts (`content/posts/{en,ja}/`)
 
**Structure:**
1. **Hook** (1–2 paragraphs) — Start with the problem or outcome
2. **Body** — Logical sections with descriptive headings
3. **Closing** — Transferable insights in 3–4 bullets
 
**Voice:** First person ("I discovered"), share opinions, acknowledge limitations

When I ask Claude Code to "write a blog post about this topic," it generates content that adheres to the project's style guide. Everything from title formatting to description writing to code block notation follows a consistent format.

5. Development Guidelines — Project-Specific Conventions

The final section documents this project's unique development principles.

### Project-Specific Practices
 
**This blog's patterns:**
- **Content-first development** — Features exist to enhance content, not vice versa
- **Progressive enhancement** — Core content readable without JavaScript
- **Bilingual parity** — Features must work equally well in both locales
- **Static-first** — Prefer build-time generation over runtime computation

These principles help Claude Code generate not just working code, but code that aligns with the project's philosophy. When implementing new features, it considers questions like "Is content readable without JavaScript?" and "Does this work equally well in both Japanese and English?"

Real-World Impact: Dramatically Improved AI Collaboration

Since introducing CLAUDE.md, collaboration with Claude Code has improved dramatically. Here are three specific improvements.

1. Accurate Command Execution

Previously, when asked to "run tests," Claude Code might suggest non-existent commands like npm run test or jest. After implementing CLAUDE.md, it consistently uses the correct command (npm test) and selects appropriate tests (unit vs E2E) based on the changes.

2. Convention-Compliant Code Generation

Claude Code now accurately understands project-specific tech stack details: Tailwind CSS v4's new syntax, Velite's content structure, and Server Component distinctions. Notably, it now understands the #site/content alias and properly imports Velite-generated content — a significant improvement.

3. Style Guide-Compliant Content Creation

When asked to create blog posts or TIL entries, everything from title formatting to frontmatter structure to body organization follows the style guide. It properly implements details like "specific and outcome-oriented titles," "first-person writing," and "closing with transferable insights."

Implementation Tips: Writing Effective CLAUDE.md

Here are three key points I focused on when writing CLAUDE.md.

1. Include Abundant Concrete Examples

AI understands concrete code and command examples better than abstract descriptions. Instead of "write tests," specify "src/lib/ changes → add tests in __tests__/lib/" with concrete paths and actions.

2. Use Tables and Flow Diagrams

Complex information is easier to understand in tables and flow diagrams than bullet points. I actively used visual representations like the Tech Stack table and Content Pipeline flow diagram.

3. Explain the "Why"

Don't just list rules — include the reasoning behind them. Why do we have a "Content-first development" principle? Why did we choose "No external i18n library"? This helps AI understand not just surface-level rules but the project's philosophy, enabling better decision-making.

An Easy-to-Miss Pitfall: Making Implicit Expectations Explicit

You've written CLAUDE.md, but Claude Code still doesn't behave as intended — sound familiar? Practical Claude Code (Gijutsu-Hyoron) identifies the root cause: implicit expectations that aren't documented.

Steps Experts Consider "Obvious"

When asked to "add a profile editing feature," an expert developer naturally follows these steps:

1. Read README.md to understand the overall project
2. Check architecture.md to understand the layer structure
3. Grep for existing similar features
4. Read the found implementations to understand patterns
5. Implement the new feature following those existing patterns
6. Run tests

But if CLAUDE.md only says "When implementing new features, always check README.md and architecture.md" — what happens? Steps 3-5 (searching for and following existing patterns) aren't documented, so Claude Code treats them as "optional." It starts implementing based solely on architecture.md, producing code that follows different patterns from the existing codebase.

For experts, "searching for similar features and matching existing patterns" is so natural that documenting it never occurs to them. But for Claude Code, steps not written in CLAUDE.md aren't mandatory.

Another Trap: Conflicting Instructions Across Documents

Similar to implicit expectations, contradictory instructions across multiple documents cause problems. For example:

• architecture.md: "UI layer must always access data through the service layer"
• development-guidelines.md: "For performance-critical screens, access data sources directly"
• Existing Dashboard.tsx: Implemented with direct data access

When asked to "extend the dashboard," Claude Code faces three conflicting signals. Without explicit guidance on which takes priority, it may adopt different patterns each time — producing unstable behavior.

The Fix: Write Down Your Tacit Knowledge

The solution is consciously documenting what you consider "obvious." These questions help surface blind spots:

• "What do I actually do first when implementing a new feature?" — Identify the unconscious steps: searching, checking existing patterns, referencing design docs
• "Do any of my documents contradict each other?" — When rules conflict, state the priority explicitly
• "Would a new hire take the same actions from reading this?" — Imagining a junior developer reveals assumptions you've been taking for granted

To maximize CLAUDE.md's effectiveness, don't just write rules — document the procedures for following those rules.

CLAUDE.md Limitations and Future Outlook

CLAUDE.md isn't perfect. It has current limitations.

First, there's the maintenance cost issue. Every time the project structure changes, CLAUDE.md needs updating. Neglecting this means giving AI incorrect information. I currently address this by including CLAUDE.md updates as a mandatory task in our architecture change checklist.

There's also variance in AI model comprehension. Guidelines optimized for Claude Code might not work equally well with other AI assistants. In the future, we might need a more universal format that works across multiple AI assistants.

Summary

• Design an AI-specific interface, not another README — A README targets human readers. CLAUDE.md targets AI, providing the technical details and coding conventions that enable convention-compliant code generation.
• Concrete examples beat abstract descriptions — Specific paths, exact commands, and real code snippets give AI far more actionable guidance than vague prose like "follow project conventions."
• A bloated CLAUDE.md backfires — Because the file is loaded into the context window every session, cramming in too much detail causes the AI to miss the instructions that actually matter.
• State the "why" behind each rule — When AI understands the reasoning, it can generalize to novel situations rather than blindly pattern-matching against examples.
• Write down your implicit steps — The procedures experts consider "obvious" are exactly what tends to be missing from CLAUDE.md. Use "Would a new hire do the same thing?" as your litmus test.

If you're using AI coding assistants, definitely consider implementing CLAUDE.md. Start simple with a command list and architecture description, then gradually expand it. Your AI collaboration will surely become more comfortable.

However, there's a catch — expand it too much and CLAUDE.md bloat actually degrades AI performance. In the next post, I cover how I reduced my bloated 355-line CLAUDE.md by 83% using a skills system.