# Global Instructions I am not a developer. I build projects by describing what I want in plain language. Treat me as a smart, capable person who does not know programming terminology or conventions. These rules apply to every project. For full personal context, business details, team info, and preferences, read `~/Claude-Memory/CLAUDE.md` and the sub-files it points to. # Security (Critical) ## API Keys and Secrets - NEVER hardcode API keys, passwords, tokens, or secrets in code files - ALWAYS use .env files for secrets and add .env to .gitignore immediately - Before any git command on a file headed to GitHub, check that no secrets are included - If I accidentally paste an API key into chat or a file, warn me immediately and help me rotate it ## Package Installation — How to Report Findings A [[Hooks|hook]] intercepts every `npm install`, `npm i`, `pnpm add`, `pnpm install`, `pnpm i`, `yarn add`, `pip install`, and `pip3 install` command and runs a Socket.dev security check before anything installs. When the hook blocks an install and returns findings, report them in this format: **Package:** [name] **What it does:** [one sentence] **Weekly downloads / last updated:** [from Socket.dev or web] **Socket.dev findings:** [exact output from the hook, in plain English] **Verdict:** SAFE / CAUTION / DO NOT INSTALL / UNVERIFIED **Reasoning:** [plain English, no jargon] Then stop and wait for me to type "yes, install it" or "go ahead." Do not retry the install for any other reason. If Socket.dev was unreachable and returned no data, your verdict must be UNVERIFIED — search the web for "[package name] security vulnerability" and "[package name] supply chain attack," include what you find, and still wait for my approval. ### Automatic DO NOT INSTALL Triggers If any of these are present, verdict must be DO NOT INSTALL and you must tell me why before asking anything: - Supply chain risk or malware flagged on Socket.dev - Typosquatting warning - Critical or high severity vulnerability in the current version - Recently transferred to a new maintainer with no track record - Fewer than 50,000 weekly downloads for a package claiming wide adoption - No updates in over a year (unless it is a stable, finished utility) - Requests unnecessary system-level permissions ### Transitive Dependencies If installing Package A also pulls in B and C automatically, check all of them. If you can't feasibly check them all, list every package that will be installed and tell me before proceeding. ## Scripts and Network Requests - Never run a script downloaded from the internet without first explaining exactly what it does, line by line if needed - If code makes network requests to external services, tell me which services, what data is sent, and why, before running it # Safety and Confirmation - Before deleting, overwriting, or significantly changing existing files, tell me what's affected and ask for confirmation - Before any command that modifies system settings, installs global software, or changes config outside the project folder, explain it and ask for confirmation - A hook blocks `git push --force`, `git reset --hard`, and `rm -rf`. If you need one, explain why and ask for my explicit approval before retrying - If you're unsure about the right approach, ask me rather than guessing # Code Quality - Keep code simple and readable; prefer straightforward solutions over clever ones - Add brief comments explaining what each section does so I can follow along - Start with the simplest working version, then improve - Don't add features, complexity, or "improvements" I didn't ask for - If you spot a problem in my existing code, tell me — don't silently fix it - Database: PostgreSQL — don't add a database unless I specifically ask - I don't want my apps to be able to fail silently. Build in error tracking and notifications so a failure reaches me instead of sitting quietly in a log # Project Organisation - Keep files in clear folders with obvious names; explain the structure for new projects - Always create a .gitignore that excludes node_modules and other standard ignores - If a project has no version control, suggest it and explain why it matters ## Three roots: ~/Code, ~/AI-Work, ~/CoWork My work splits across three folders that share one relative path, so swapping the root gets you the matching half — no lookup needed. `~/Code/Project A/` pairs with `~/AI-Work/Project A/`. - **`~/Code`** — code. Everything here goes to GitHub. Technical documentation stays in the repo beside the code. - **`~/AI-Work`** — the Obsidian vault: briefs, build prompts, design prompts, planning notes. Syncs to my phone. Read it when you need project background, not by default. - **`~/CoWork`** — data files I work on with Claude: spreadsheets, exports, client reports. Never goes to GitHub. Backed up to cloud storage instead. Read access to `~/AI-Work` and `~/CoWork` is granted once in `~/.claude/settings.json`, so no folder needs adding to any project. **Never put client data or any non-code files in `~/Code`.** A folder there can be committed and pushed by accident; `~/CoWork` cannot. Never `git init` anything inside `~/CoWork`. # Dependencies and Packages - Prefer well-known, actively maintained packages with large communities - Before adding a dependency, check if the functionality already exists or can be done simply without one - Warn me about deprecated or archived packages - When updating packages, explain what changed and what might break # Error Handling - Explain errors in plain language first, then suggest fixes - Don't silently catch and hide errors — I need to know when things go wrong - If an approach isn't working after two attempts, stop and explain rather than trying endless variations # Backup and Recovery - Before large changes to a working project, suggest a backup or git commit - Never overwrite working code without a way to get it back - If I ask you to undo something, explain what will be restored and what might be lost # Memory At the end of each session, write a 5–8 bullet summary of what was completed and what's still pending to `context-log.md` in the project root. Create the file if it doesn't exist. ## One event, one home Writing the same event into four files gives you four accounts that drift apart as the code moves on. Each kind of record has exactly one home: | What you're recording | Where it goes | |---|---| | What this session did | `context-log.md` | | How the system works **now** | `TECHNICAL_DOCUMENTATION.md` — state, never history | | A deploy and its post-mortem | `deploy-log.md` | | A standing rule, or a trap that would cost another incident | `CLAUDE.md` | **A file that accumulates dated `##` headings is in the wrong shape.** A manual whose sections are dates is a changelog wearing a manual's name — ask it "how does login work?" and you get every historical account to reconcile instead of one answer. ## Keep this file small `CLAUDE.md` is prepended to every session, so anything appended here is paid for on every future run, forever. **Ceiling ~25 KB, target under 200 lines** — past that, adherence drops as well as budget. Only two things earn a place: a rule that changes what a future session may do, or a trap that would otherwise cost another incident. Corrections replace the wrong text rather than sitting beside it; git holds the history. Run `wc -c CLAUDE.md` before you commit. Two mechanisms genuinely defer cost, and `@import` is not one of them — imports load at launch, so they organise without saving anything. **Skills** load only when invoked, and **`.claude/rules/*.md` with `paths:` frontmatter** load only when a matching file is read. ⚠️ **Never move a safety rule into a path-scoped rule file to shrink this one.** Path-scoped rules are not re-injected after `/compact`, while a project-root `CLAUDE.md` is. A long autonomous run compacts repeatedly, so a permission boundary or deploy guardrail moved there would silently stop applying part-way through — a control that reads as enforcement and executes nothing. Fine for file-type conventions, never for rules. ## Never load a log file at session start Two [[Hooks|hooks]] assist, and **neither blocks** — both only print. `session-snapshot.sh` (`SessionStart`) prints about 1.4 KB of *computed* state: branch, uncommitted count, recent commits, recent session titles sorted by date, and any open `## Needs Human` items. It never opens a log file. `session-log-check.sh` (`Stop`) measures what the session actually appended and reports one of: nothing written, more than 4 KB written, or the live log past 150 KB so rotation is due. **No context log is auto-loaded. Open one yourself when you need prior-session history — and never read it whole.** A 250 KB log costs roughly 62,000 tokens to read, half a context window, to find one paragraph. Instead: 1. `grep -n '^## ' context-log*.md` — the index. Every entry is a dated heading. **The `*` is load-bearing** in any project that has rotated: without it you silently stop at the current period and still get results. 2. Read only that line range, or `grep -n -i '' context-log*.md` to search by topic and read around the hits. Sort that index **by date, not by position** — sessions append to both the top and the bottom of these files, so `head` or `tail` alone can miss the newest entry. **Rotation.** When `context-log.md` passes ~150 KB, or at a quarter boundary, move the oldest complete period into `context-log--Q.md` **beside it at the project root** — flat, never a subdirectory, because entries contain relative links that a depth change would break. Archives are frozen; append only to `context-log.md`. Two things to check before your first rotation, both of which fail silently, are in [[Project memory - what your AI loads before you type|the memory note]]. # Skills - Available skills are injected into context at session start. Keep a human-readable inventory at `~/.claude/skills-inventory.md`. - Custom skills trigger ONLY on explicit invocation — never on a casual phrase. Any skill that can run unattended must pause at a confirmation gate first. - `/graphify`: when I type it, invoke the graphify skill before anything else. When you need to understand a codebase, read the knowledge graph first. # Agent Team Policy Propose an agent team when: the task has 3+ clearly independent workstreams, parallel research benefits from multiple perspectives, or changes cross layers (frontend + backend + tests). Do NOT spawn a team for: tasks under ~30 min of single-agent work, same-file edits, or sequential tasks with hard dependencies.