9.2 KiB
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.txtandreports/(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 /<filename> 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):
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):
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/commandsalready exists with your own commands, move them intoslash-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 |
<project>/.claude/commands/ |
Only that project |
The filename becomes the command name — update-deps.md → /update-deps.
Option 1 — scp from your Windows machine
- On the server, create the folder (one time):
mkdir -p ~/.claude/commands - From PowerShell on your Windows machine, copy the file over:
To copy every slash command at once:
scp C:\AI\slash-commands\update-deps.md <user>@<server>:~/.claude/commands/scp C:\AI\slash-commands\*.md <user>@<server>:~/.claude/commands/
Option 2 — nano directly on the server
- SSH into the server and create the folder (one time):
mkdir -p ~/.claude/commands - Open a new file named after the command:
nano ~/.claude/commands/update-deps.md - 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 orCtrl+Shift+Vin most terminals - Save and exit:
Ctrl+O,Enter, thenCtrl+X
Verify
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.
- Copy the content of
CLAUDE.md(and any relevantpreferences/files) into a file named.cursorrulesin 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.mdinto 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.mdas 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.mdthere
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.mdDetailed 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 fromCLAUDE.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.jsonis 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.mdshould stay concise — it's the quick-reference. Put detail inpreferences/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