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/CLAUDE.md globally, and any CLAUDE.md in a project root. Global preferences apply everywhere; project-level adds on top.

Recommended setup (symlinks + auto-pull across machines):

Clone this repo locally and symlink CLAUDE.md and preferences/ into ~/.claude/. From that point on, git pull is the only sync step — and the auto-pull hook in preferences/hooks-setup.md handles that automatically on every session.

Linux (one-time setup per machine):

git clone https://git.chns.tech/CHNS/AI ~/AI
ln -sf ~/AI/CLAUDE.md ~/.claude/CLAUDE.md
ln -sf ~/AI/preferences ~/.claude/preferences

Windows (one-time setup — requires Developer Mode or run PowerShell as Administrator):

git clone https://git.chns.tech/CHNS/AI C:\AI
Remove-Item "$env:USERPROFILE\.claude\CLAUDE.md" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.claude\preferences" -Recurse -Force -ErrorAction SilentlyContinue
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\CLAUDE.md" -Target "C:\AI\CLAUDE.md"
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\preferences" -Target "C:\AI\preferences"

After symlinking, configure hooks from preferences/hooks-setup.md — the auto-pull hook will keep preferences current automatically.

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 symlink setup, no manual copy step is needed. Edit the repo files directly — the symlinks mean ~/.claude/ always reflects the latest committed content. The auto-pull hook fetches remote changes automatically at the start of each session.

Hooks are not synced automatically. ~/.claude/settings.json is machine-local and not part of this repo. After cloning and symlinking 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'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