# 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/ │ ├── docker-security-audit.md # Vulnerability/secrets audit of Docker images (Trivy, Grype) │ ├── M365-Graph-Form-Email-Setup.md # Website form → email via FastAPI + Microsoft Graph (M365 tenant) │ ├── service-golive.md # Pre-go-live review checklist for services exposed via NPM │ └── service-update.md # Recurring maintenance review for already-live services ├── 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 └── slash-commands/ └── update-deps.md # /update-deps — audit, update, test, and commit all dependencies ``` > `containers.local.txt` and `reports/` (used by the Docker security audit playbook) are git-ignored. **`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 and setup guides for specific tasks. Each playbook is invoked on demand — tell the AI to use it (pointing at its raw URL, e.g. `https://git.chns.tech/CHNS/AI/raw/branch/main/playbooks/service-golive.md`) and it walks through the steps interactively. **`slash-commands/`** contains Claude Code custom slash commands. Each file becomes `/` once linked into `~/.claude/commands/` (see setup below). --- ## 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`, `preferences/`, and `slash-commands/` (as `commands/`) 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 ln -sfn ~/AI/slash-commands ~/.claude/commands ``` **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" New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\commands" -Target "C:\AI\slash-commands" ``` > If `~/.claude/commands` already exists with your own commands, move them into `slash-commands/` first (or symlink individual files instead of the folder). After symlinking, configure hooks from `preferences/hooks-setup.md` — the auto-pull hook will keep preferences current automatically. --- ### Slash Commands on an Ubuntu Server (Manual Copy) Use this when you want a slash command on a server without cloning the repo. Manually copied files **do not auto-update** — repeat the copy after changing a command. Where the file goes decides where the command works: | Location | Scope | |---|---| | `~/.claude/commands/` | Every project for that user on the server | | `/.claude/commands/` | Only that project | The filename becomes the command name — `update-deps.md` → `/update-deps`. **Option 1 — `scp` from your Windows machine** 1. On the server, create the folder (one time): ```bash mkdir -p ~/.claude/commands ``` 2. From PowerShell on your Windows machine, copy the file over: ```powershell scp C:\AI\slash-commands\update-deps.md @:~/.claude/commands/ ``` To copy every slash command at once: ```powershell scp C:\AI\slash-commands\*.md @:~/.claude/commands/ ``` **Option 2 — `nano` directly on the server** 1. SSH into the server and create the folder (one time): ```bash mkdir -p ~/.claude/commands ``` 2. Open a new file named after the command: ```bash nano ~/.claude/commands/update-deps.md ``` 3. Open the file in Gitea (`https://git.chns.tech/CHNS/AI/src/branch/main/slash-commands/`), copy the full contents (including the `---` front matter at the top), and paste into nano — right-click or `Ctrl+Shift+V` in most terminals 4. Save and exit: `Ctrl+O`, `Enter`, then `Ctrl+X` **Verify** ```bash ls ~/.claude/commands/ ``` Start a new Claude Code session on the server and type `/` — the command should appear in the list. --- ### 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