使用 Claude Code 進行 AI 輔助編碼的最佳實踐與建構 Claude.md

Best Practices for AI-Assisted Coding with Claude Code

Table of Contents

Introduction: Why This Guide is Different

AI-first development workflows are still shaky to implement across the industry and I’ve found that it’s difficult to find trustworthy and knowledgeable source of information on how to do so effectively. Since we’re currently experiencing the wild west of AI dev workflows, I figured I’d add my own two cents into the conversation.

In particular, it’s been frustrating to see tons of “best practices” content that I’d consider inadequate when trying to learn how to run a team or just your own dev workflow. The majority of articles I’ve found are:

The Tool Landscape

Let’s address the elephant in the room: which tool should you use?

Over the past 18 months, I’ve used Gemini, Codex, Cursor, Claude Code, Co-Pilot, OpenCode, and several others. And ChatGPT directly for longer before that. The consensus—both mine and the community’s—is that Claude Code is currently the best.

The problem is that tooling is currently moving so fast that Claude code may not be the top choice forever. Worse yet, the tool itself goes through minute (and larger) updates which entirely destabilize any consistent approach to using it.

For example, I’ve found Claude to be less certain of itself in the past few weeks, and it’s been more likely to give me options rather than solve problems outright. And that’s despite the fact that it’s been using the same models for almost a year now.

Target Audience

These best practices are specifically aimed at:

While the tooling does progress and update constantly, we can take a more abstract approach to best practices – some that concretely work across the updates and some that are more process-involved.

Core Best Practice: Write Your Own CLAUDE.md

Your CLAUDE.md (or AGENTS.md) is the first file that your claude core or any other agentic tool will look at. This is your opportunity to set the expectation with the AI tooling and help it understand your code and your dev workflows.

I find that just running /init provides a solid starting point but for larger projects than your weekend todo list project, you should absolutely write your own CLAUDE.md by hand. Use the initialized file as a starting point but from then on, make sure to directly be involved in how claude code approaches the work it’s supposed to do.

The ROI on taking a few initial hours to setup this file is immense, especially over the course of a long-running project.

Note: You may have found your own method of prompting claude and that’s great! This post is supposed to provide my own opinionated approach to prompting claude and utilizing it to its maximum potential.

Language – how to write

I’ve found that CC works very well with imperative direct language. The agent file should be as clear as possible. Short sentences, do/don’ts, etc.

For example:

Another good way of thinking about this is to approach your CLAUDE.md like an onboarding document for a developer joining the codebase. And while you may have been promised that CC will completely replace dev-onboarding for codebase, you really do want to provide this structured onboarding for the AI. If there’s anything you’d want to tell your developer about working in a codebase, tell Claude, too.

Think of it this way: You don’t want your AI to second-guess itself and you don’t want it to infer how to contribute to your codebase.

Recommended Structure

I’m providing a general structure to your CLAUDE.md; however, structure it as close to what makes sense for your project as possible. This will be iterative work but my structure is here to provide a starting point.

As an example, I’ll be using my UI library Cottage UI

Here’s how to structure your CLAUDE.md:

Start with what your project is about. Be specific.

Be explicit about file organization. The more structured your explanation, the easier it is for Claude to understand what it’s looking for when working on a task.

For larger applications, describe major sections:

Tip: Make sure to reference other docs in your CLAUDE.md if you have them.

Every codebase has a deprecated something. Whether that’s a pattern, library, or entire endpoints, specify what Claude should avoid using and what it should prefer using.

List preferred libraries and, importantly, deprecated ones:

Make sure to spell out your standards to the AI. There are multiple ways of doing that incredibly well:

Claude and other AIs work incredibly well off explanations and examples so it’s important to mix both. It’s also important to let it know about all standards and your expectations.

There will be a more in-depth analysis of this section below.

Here’s a great example of some of these patterns:

I find it important to add a detailed section like this for every major part of the codebase. If it feels like you’re writing a 200 page essay, the most helpful tip I can give you here is to write separate README.md files for each large section, co-locate it with the code, and reference it in the CLAUDE.md. eg.

Tip: Give your AI relative links to additional documentation so it can dive into a subject of its choosing when needed. When doing so, make sure to explain when and why to access this additional documentation

I’ve found that giving the AI links and describing when it should access that documentation lets the AI load that context when needed and it lets you be as expansive in your descriptions and examples as you want to be without sacrificing your context window.

Explain your development workflow explicitly:

Tip: Give your AI external links to valuable docs so that it can follow opensource and public documentation.

Writing Style: Clear and Explicit

Repeat yourself liberally. It’s better to repeat than have Claude assume wrongly.

Even if something seems clear, repetition reinforces the keywords and patterns. Use:

A great example is a flatten folder structure tree:

The No-Nos List

Create an explicit list of things Claude should not do:

Be literal. Don’t say “API contracts should be stable” – say ”DO NOT change the API contracts.”

Tip: Working with Claude is an iterative process. Whenever you come across a behavior you don’t want, add it to the Do Not Do list. It’ll help steer Claude down the right direction.

Further Resources

Further resources can be supplied via internal documentation and linking to them or by supplying external documentation. Ensure you explain why and when this information should be accessed.

You can specify these inline (like in some examples above) or in its own section.

Leverage Examples and Templates

AI excels with concrete examples and templates. Provide as many as possible.

Templates

If you have a specific pattern in your codebase, create a template. It can be as comprehensive and detailed as you want it to be. I wrote an article on my ideal react component and I still use it as a template for React but it doesn’t have to be this detailed.

Example: If you use Mock Service Worker for every integration test:

Tip: You can hint to the AI when there are commonly-used utilities/libraries and when to use them.

Using Real Files as Templates

Templates don’t have to be blank scaffolding. You can use a real, trusted file as reference:

This approach has a huge advantage: templates stay up-to-date automatically. If you reference an existing file that evolves with your codebase, you never have stale templates. The downside is that if this files goes untouched for a longer time period, it can provide Claude with a stale example. The great thing is that as soon as you recognize it, you can update CLAUDE.md immediately and fix the issue for you and your colleagues.

Iterative Improvement

With Claude, every frustration is an opportunity to improve your setup. The huge upside of LLMs is that you can actually affect your tooling instead of having to put up with unwanted behavior.

This goes both ways, if Claude surprises you with a positive pattern, you can reinforce that pattern.

Some examples:

Claude changes your .env. If it’s unwanted behavior, update your CLAUDE.md with DO NOT update .env files

Claude bootstraps your tests more efficiently. If it’s wanted behavior, update your CLAUDE.md with the directions on how to do it – or ask Claude to update its own directions.

Specify Expected Output

Beyond describing inputs (your codebase) and process (workflow), specify the output format you want. Templates and examplse fall into this category but you can do this with other aspects of your AI use.

Planning Workflow Example

I like to ask Claude to plan before executing major changes. You can specify this:

LLMs work really well when you tell them exactly what you need, including the format.

Documentation: The Foundation

I’m listing this last, but it should really be your first priority: Write documentation for your project.

Root README.md

Create a comprehensive entry point for that onboarding developer and for any developer learning about the codebase:

Much of this might overlap with claude.md, but that’s fine. Claude works really well when you treat it like a regular developer learning a new codebase.

Folder-Level Documentation

Extend the README pattern to any confusing or complex parts of the codebase so that key parts or domains have their own documentation to get a developer working there:

/tests/README.md

Complex Component Documentation

For complicated subsystems, create dedicated README files.

Example: ETL Pipeline

/src/etl/README.md

Next Steps

Ok, so now you have a good understanding of how to build a solid CLAUDE.md or an AGENTS.md file but it feels like a lot of work, right?

It’s always much easier to start with something than nothing and then iterate. And your OpenCode or Claude code or Gemini or Codex can do just that by reading this article and using it as its own template for its agent file. Then, you can iterate on the documentation and agent file as you work with your AI development companion.

Through this iterative process, you’ll end up with a codebase that’s:

The key is treating AI coding tools like team members who need good onboarding, clear guidelines, and continuous feedback. The time you invest in documentation and structure pays dividends in faster, more accurate AI-assisted development.

If you want more examples, you can check out the Cottage UI repository where I’m experimenting with Claude, OpenCode, and all kinds of agents to get the best workflow down.

I’d also suggest referencing this article in your CLAUDE.md in case you want to update your CLAUDE.md or need help extending/structuring your documentation and existing CLAUDE.md.

Exploring web development, technology trends, and digital craftsmanship.

Navigation

Connect

© 2026 AntJanus. All rights reserved.