# AI Preferences

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):**

```bash
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):**

```powershell
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.

1. Copy the content of `CLAUDE.md` (and any relevant `preferences/` files) into a file named `.cursorrules` in your project root
2. 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.

1. In your project, create `.github/copilot-instructions.md`
2. Paste the content from `CLAUDE.md` into that file
3. 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.

1. Open `CLAUDE.md`
2. Copy the full contents
3. 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:

1. Use `CLAUDE.md` as your base — it's written to be tool-agnostic
2. Look for the tool's "system prompt", "custom instructions", or "rules" setting
3. 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):**
1. Open the relevant `preferences/` file
2. Edit the specific rule
3. Commit: `git commit -m "Update [topic] preference"`

**New topic area (e.g., you start working with a new stack):**
1. Create a new file in `preferences/` — e.g., `preferences/hugo-blog.md`
2. Add a link to it in the `CLAUDE.md` Detailed References section
3. Commit both files together

**Removing something outdated:**
1. Delete or edit the relevant section
2. 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