How to Add Project-Specific Guidelines to an Existing CLAUDE.md File

You can customize Claude Code's behavior by appending a ## Project-Specific Guidelines section to your CLAUDE.md file, which the Claude Code plugin automatically reads at runtime without requiring additional configuration.

The forrestchang/andrej-karpathy-skills repository provides a foundational CLAUDE.md file containing four universal coding principles that guide Claude Code interactions. To tailor these instructions to your specific codebase—adding language-specific rules, testing requirements, or deployment conventions—you extend the existing file rather than replacing it, preserving the core safety principles while injecting project context.

Understanding the Base CLAUDE.md Structure

The canonical CLAUDE.md in the repository root (/cache/repos/github.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md) establishes four core behavioral principles: Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution. These principles form the base instruction set that Claude Code uses for every interaction, ensuring consistent behavior across projects.

Because the file is read dynamically by the Claude Code plugin—according to the metadata defined in .claude-plugin/plugin.json—any modifications you make to the file immediately influence Claude's behavior in subsequent sessions.

Steps to Add Project-Specific Guidelines

To add project-specific guidelines to existing CLAUDE.md, append a new markdown section after the original content. This approach preserves the four core principles while adding your custom constraints.

Step 1: Locate or Create the CLAUDE.md File

If your project does not yet contain the base file, fetch it from the upstream repository:

curl -sSL https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md > CLAUDE.md

Place this file in your project root so the Claude Code plugin can locate it according to the plugin configuration.

Step 2: Append the Project-Specific Section

Add a markdown heading ## Project-Specific Guidelines followed by your custom rules. According to the repository's README.md (lines 39-52), this section should contain project-specific constraints such as linting rules, required testing frameworks, or security policies.

List each guideline as a bullet point beneath the heading. The Claude Code plugin parses this section at runtime and incorporates these rules alongside the four base principles.

Step 3: Commit Your Changes

Once you append the section, commit the modified CLAUDE.md to your repository. Future Claude Code sessions automatically pick up the extended guidance without requiring plugin restarts or environment variable changes.

Code Examples for Appending Guidelines

Here are practical methods to add project-specific guidelines to existing CLAUDE.md programmatically.

Append Using Unix Shell Commands

Use printf and cat to add the section without opening an editor:

# Add a blank line then the new section to the end of CLAUDE.md

printf "\n## Project-Specific Guidelines\n\n" >> CLAUDE.md

cat <<'EOF' >> CLAUDE.md
- Enable TypeScript `strict` mode for all new files
- Every public API endpoint must have an associated Jest test
- Follow the error-handling pattern defined in `src/utils/errors.ts`
EOF

Fetch Upstream and Extend

If you want to ensure you have the latest base principles before adding your own:

# Fetch the upstream CLAUDE.md

curl -sSL https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md > CLAUDE.md

# Append project-specific rules

cat <<'EOF' >> CLAUDE.md

## Project-Specific Guidelines

- All database migrations must be reviewed by the DB-architect team
- Use Prettier with the project's `.prettierrc` configuration
- Do not commit generated files under `dist/`
EOF

Expected File Structure

Your final CLAUDE.md should look like this:

# CLAUDE.md

... (original four principles) ...

## Project-Specific Guidelines

- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`

How the Claude Code Plugin Reads Your Guidelines

The .claude-plugin/plugin.json file defines the Claude Code plugin metadata, ensuring the plugin loads the CLAUDE.md file for each project at runtime. Because the plugin reads this file dynamically, any changes you commit to CLAUDE.md—including your appended project-specific guidelines—immediately influence Claude's behavior in subsequent sessions.

This runtime loading mechanism means you do not need to configure environment variables or restart the Claude Code client; simply committing the updated CLAUDE.md to your repository root is sufficient.

Summary

• Locate the base CLAUDE.md from the forrestchang/andrej-karpathy-skills repository to establish the four core principles.

• Append a ## Project-Specific Guidelines section to add project-specific rules without modifying the original principles.

• Use shell commands or manual editing to add the section, then commit the changes to your repository.

• The Claude Code plugin reads CLAUDE.md at runtime, so updates apply automatically to future sessions.

Frequently Asked Questions

What are the four core principles in the base CLAUDE.md?

The base CLAUDE.md contains Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution. These principles guide Claude Code to plan before implementing, prefer simple solutions, make minimal targeted changes, and focus strictly on task completion rather than scope creep.

Can I modify the existing four principles instead of appending?

While you technically can edit the base principles, the repository design expects you to preserve the original four principles in CLAUDE.md and extend them via the ## Project-Specific Guidelines section. This approach ensures you retain the core behavioral safety rules while adding project context, preventing accidental degradation of Claude's fundamental operating constraints.

Where should I place the CLAUDE.md file in my project?

Place CLAUDE.md in your project root directory. The Claude Code plugin configuration in .claude-plugin/plugin.json specifies that the plugin looks for this file at the project root to load instructions at runtime. The file must be named exactly CLAUDE.md (case-sensitive) for the plugin to recognize it.

Do I need to restart Claude Code after updating CLAUDE.md?

No. The Claude Code plugin reads the CLAUDE.md file at runtime for each session, so any committed changes—including newly appended project-specific guidelines—are automatically picked up without requiring a restart or additional configuration. However, the file must be committed to your repository; uncommitted changes in the working directory may not be picked up immediately.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}