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

> Easily customize Claude Code behavior by adding project specific guidelines to your CLAUDE.md file. Discover how to enhance model responses without extra configuration for your projects.

- Repository: [Jiayuan Zhang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)
- Tags: how-to-guide
- Published: 2026-04-08

---

**You can customize Claude Code's behavior by appending a `## Project-Specific Guidelines` section to your [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) in the repository root ([`/cache/repos/github.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main//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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.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:

```bash
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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) should look like this:

```markdown

# 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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.claude-plugin/plugin.json) file defines the Claude Code plugin metadata, ensuring the plugin loads the [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) file for each project at runtime. Because the plugin reads this file dynamically, any changes you commit to [`CLAUDE.md`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md) in your project root directory. The Claude Code plugin configuration in [`.claude-plugin/plugin.json`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/.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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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`](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/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.