A personal repository of markdown files that define how AI systems should work with me. Instead of re-explaining preferences every session, these files act as a persistent "operating manual" that can be loaded into any AI tool.

What's in This Repo

AI/
├── CLAUDE.md                          # Main entry point — loaded automatically by Claude Code
├── playbooks/
│   └── service-golive.md              # Pre-go-live review checklist for services exposed via NPM
└── preferences/
    ├── articles.md                    # Blog post writing guide for chns.tech (Hugo/Markdown)
    ├── communication.md               # How I like responses structured and how to interact
    ├── hooks-setup.md                 # Required Claude Code hooks and setup instructions
    ├── powershell-wpf.md              # Standards for PowerShell and WPF applications
    ├── python-web.md                  # Standards for FastAPI, SQLAlchemy, Docker Compose
    └── project-structure.md           # Standard folder layouts per project type

CLAUDE.md is the top-level summary. It references the preferences/ files for detail. This is the file you point AI tools to — or it gets picked up automatically.

preferences/ contains the detail files. Each covers a specific domain. You generally don't point tools directly at these; CLAUDE.md references them for context.

playbooks/ contains step-by-step AI-guided checklists for specific tasks. Each playbook is invoked on demand — tell the AI to use it and it walks through the steps interactively.

How to Use These Files

Claude Code (Automatic)

Claude Code automatically reads CLAUDE.md from the root of any project it's working in.

Option A — Per project: Copy CLAUDE.md into the root of any project repo. Claude Code will pick it up automatically every session.

Option B — Global (recommended): Place CLAUDE.md in your Claude global config folder so it applies to every project without copying:

# Windows
Copy-Item "CLAUDE.md" "$env:USERPROFILE\.claude\CLAUDE.md"

Note: If a project also has its own CLAUDE.md, Claude Code merges both — global preferences apply everywhere, project-specific ones add on top.

Cursor

Cursor reads a .cursorrules file in the project root.

Copy the content of CLAUDE.md (and any relevant preferences/ files) into a file named .cursorrules in your project root
Cursor will load it automatically as context for all AI interactions in that project

GitHub Copilot (VS Code)

Copilot reads custom instructions from VS Code settings or a .github/copilot-instructions.md file.

In your project, create .github/copilot-instructions.md
Paste the content from CLAUDE.md into that file
Copilot will use it as persistent context for that workspace

ChatGPT / Claude.ai (Manual)

These tools don't auto-load files, so you paste preferences at the start of a conversation.

Open CLAUDE.md
Copy the full contents
Paste it as the first message in a new conversation with the instruction: "These are my preferences. Follow them for this session."

Other AI Tools

Most AI tools support some form of system prompt or custom instructions. The general approach:

Use CLAUDE.md as your base — it's written to be tool-agnostic
Look for the tool's "system prompt", "custom instructions", or "rules" setting
Paste the contents of CLAUDE.md there

Keeping Preferences Up to Date

Preferences should evolve as your stack and habits change. Treat this repo like any other project — update it when something no longer matches how you work.

When to Update

You adopt a new tool or framework and want it recognized as your standard
You find yourself correcting an AI on the same thing repeatedly — that's a sign it should be in the docs
A project convention changes (e.g., switching from one library to another)
You want to add a new project type template to project-structure.md

How to Update

Small change (tweak a preference):

Open the relevant preferences/ file
Edit the specific rule
Commit: git commit -m "Update [topic] preference"

New topic area (e.g., you start working with a new stack):

Create a new file in preferences/ — e.g., preferences/hugo-blog.md
Add a link to it in the CLAUDE.md Detailed References section
Commit both files together

Removing something outdated:

Delete or edit the relevant section
If a whole preferences/ file is no longer relevant, delete it and remove its link from CLAUDE.md

After Updating

If you're using the global Claude Code setup, sync your changes by running these two commands from the repo root:

Copy-Item "CLAUDE.md" "$env:USERPROFILE\.claude\CLAUDE.md" -Force
Copy-Item -Path "preferences" -Destination "$env:USERPROFILE\.claude\preferences" -Recurse -Force

Hooks are not synced automatically. ~/.claude/settings.json is machine-local and not part of this repo. After syncing preferences on a new machine, set up hooks by telling Claude Code: "Read preferences/hooks-setup.md and configure my ~/.claude/settings.json with the required hooks."

If you've copied CLAUDE.md into other project repos, re-copy the updated version to those projects
If you're using ChatGPT/Claude.ai manually, you'll be pasting the updated file next time

Tips

CLAUDE.md should stay concise — it's the quick-reference. Put detail in preferences/ files
Be specific, not general — "use SQLAlchemy 2.0 async" is more useful than "use good database practices"
Version your preferences — git history lets you see what changed and roll back if needed
One preference file per domain — don't cram everything into one file; keep it organized so it's easy to find and update