Managing AI Configuration Files Across Projects: A Private Repository Approach

If you're working with AI coding assistants like Claude Code or Cursor, you've likely encountered a familiar problem: where do you store those configuration files? You know the ones - CLAUDE.md, .cursorrules, and other AI-specific documentation that helps these tools understand your project context.

These files are incredibly valuable for maintaining consistency and providing context to AI assistants, but they don't belong in public repositories. They often contain detailed information about your codebase structure, business logic, or development patterns that you'd rather keep private. Yet, you still need version control, and if you're working in a team, you need to share them efficiently.

After wrestling with this issue across multiple projects, I've developed a solution that's been working brilliantly: a centralised private repository for all AI configuration files, connected to projects via symbolic links.

The Problem We're Solving

When I first started using Claude Code extensively, I found myself in a bind. The CLAUDE.md files I was creating contained valuable project documentation—API structures, authentication flows, business logic explanations—all the context an AI assistant needs to be genuinely helpful. But committing these to public or client repositories felt wrong.

The alternatives weren't great either:

• Adding them to .gitignore meant losing version control
• Storing them separately meant constant copy-paste operations
• Maintaining different versions across team members led to inconsistency

The Solution: Centralised Private Storage

The approach I've adopted uses a single private GitHub repository as the source of truth for all AI configuration files across all projects. Files are symlinked from this repository to their working locations, giving you the best of both worlds: version control and privacy.

Here's how it works in practice:

1. Central Repository: All AI files live in a private GitHub repository, organised by project
2. Symbolic Links: Each project contains symlinks pointing to the relevant files in the central repository
3. Version Control: Changes are committed to the private repository, not the project repository
4. Team Sharing: Team members clone the private repository and create their own symlinks

Implementation Guide

Below is the complete README from my AI-Project-Files repository. It contains everything you need to implement this approach yourself:

A private repository for AI assistant configuration files (CLAUDE.md, .cursorrules, etc.) that should not be included in public repositories.

Purpose

This repository provides version-controlled storage for AI assistant files across multiple projects while keeping them out of public/client repositories. Files are symlinked from this repo to their working locations.

Structure

claude/ # Claude Code files
├── project-name/ # Mirror of project structure
│ ├── CLAUDE.md
│ └── src/
│ └── CLAUDE.md
└── project-templates/ # Reusable templates

cursor/ # Cursor IDE files
└── project-name/
└── .cursorrules

scripts/ # Utility scripts

Setup Instructions

Initial Setup (per machine)

1. Clone this repository to your home directory:

cd ~
git clone [email protected]:repo-name/AI-Project-Files.git

Adding a New Project

1. Create the project directory structure in this repo:

cd ~/AI-Project-Files
mkdir -p claude/Your-Project-Name

2. Move your existing CLAUDE.md file(s) here:

mv ~/projects/Your-Project-Name/CLAUDE.md ~/AI-Project-Files/claude/Your-Project-Name/

3. Create symbolic link in your project:

cd ~/projects/Your-Project-Name
ln -s ~/AI-Project-Files/claude/Your-Project-Name/CLAUDE.md CLAUDE.md

4. Add to project's .gitignore:

echo "CLAUDE.md" >> .gitignore
echo "**/CLAUDE.md" >> .gitignore
echo "CLAUDE.local.md" >> .gitignore
echo "**/CLAUDE.local.md" >> .gitignore

5. Commit changes to this repo:

cd ~/AI-Project-Files
git add .
git commit -m "Add CLAUDE.md for Your-Project-Name"
git push

Working with Symlinked Files

• Edit files normally: Open CLAUDE.md in your project directory as usual
• Changes are reflected immediately: Edits apply to the actual file in this repo
• Commit changes here: After editing, commit changes in this AI-Project-Files repo
• Claude Code works normally: It reads the symlinked files without issue

Best Practices

1. Commit after changes: When you update a CLAUDE.md file, commit to this repo
2. Use descriptive commits: "Update project-name SSO auth documentation"
3. Don't store secrets: Even though private, never store passwords/keys
4. Template reuse: Store common patterns in project-templates/

Troubleshooting

Symbolic Links on Windows

Windows requires either:

• Developer mode enabled (Windows 10+)
• Run as administrator when creating links
• Use mklink instead of ln -s:
  cmd

  mklink CLAUDE.md C:\Users\you\AI-Project-Files\claude\project\CLAUDE.md
  

Link Shows as Text File

If git tracks the symlink as text:

git rm --cached CLAUDE.md
echo "CLAUDE.md" >> .gitignore
git add .gitignore
git commit -m "Remove symlink from tracking"

Finding Broken Links

find ~/projects -type l -name "CLAUDE.md" ! -exec test -e {} \; -print

Security Notes

• This repository should remain permanently private
• Carefully review before adding collaborators
• Be cautious with CI/CD that might expose these files

The Benefits in Practice

After using this system for several months, the benefits have become clear:

Version Control Without Exposure: I can track changes to my AI documentation over time, see what worked and what didn't, and roll back when needed, all without exposing sensitive information in public repositories.

Team Synchronisation: When working with other developers, we all use the same AI configuration files. Updates are shared instantly through git, ensuring our AI assistants have consistent context across the team.

Project Templates: The project-templates directory has become invaluable. I've built up a library of common patterns - authentication flows, API structures, testing approaches - that I can quickly adapt for new projects.

Clean Public Repositories: Client and open-source repositories remain focused on the actual code, without the clutter of AI-specific documentation that might confuse contributors or expose implementation details.

Considerations and Caveats

This approach isn't without its quirks. Symbolic links can be tricky on Windows (though the README covers the workarounds), and you need to remember to commit changes to the private repository after editing files. It's also one more repository to manage, though I've found the benefits far outweigh this minor overhead.

The security implications are worth considering too. While the repository is private, it becomes a single point of failure for sensitive project information. Good access control and regular auditing of collaborators is essential.

Looking Forward

As AI coding assistants become more sophisticated and integral to our development workflows, managing their configuration files will only become more important. This approach has solved my immediate needs, but I'm curious to see how the community tackles this challenge as these tools mature.

Perhaps we'll see native support for private configuration in future versions of these tools, or maybe .ai-config will become as standard as .gitignore. Until then, this symbolic link approach provides a practical solution that maintains both privacy and collaboration.

Have you faced similar challenges with AI configuration files? I'd be interested to hear how you're managing them. Feel free to adapt this approach for your own needs—just remember to keep that repository private!

For more on working with AI coding assistants, check out the Claude Code documentation and Cursor's configuration guide.