AI Usage Guidelines
& Engineering Practices

00 Purpose & Scope

Short version, for an audience that already knows the fundamentals.

AI is now part of how we build software. This document isn't an introduction to LLMs — it's the set of operational practices we agree to follow so that AI makes us faster without putting client data, security, or our reputation at risk.

It's deliberately practical: data-handling rules, tool guardrails, and runbooks you can act on — plus a short onboarding path for new team members.

01 Core Principles

Every specific rule below derives from one of these. When a situation isn't covered, reason from here.

Why we use AI at all

We use AI to speed up routine, data-heavy work and to amplify what people can do. AI is a tool: it doesn't remove responsibility, and it never makes the final decision instead of a person.

Assess the risk first

Before we build or ship anything that uses AI, we define what harm it could cause if things go wrong. The higher the risk, the more carefully we handle it — we don't skip steps just because we're under pressure.

As a rule of thumb, the higher the risk, the tighter the leash:

• Low — use AI freely; standard review is enough, and nothing sensitive gets pasted.
• Medium — use AI, but a human reviews everything before it reaches a client; verify facts, tone, and edge cases.
• High — AI assists, it never decides; mandatory expert review, extra testing, and approved tools only. When in doubt, don't.

Rules we never bend

How we put this into practice

• The maker owns it. The person who creates the work is responsible for its quality and for following these rules.
• The reviewer shares it. Whoever reviews and approves the work shares responsibility for it.
• Confirm project rules. Project-specific rules — especially client and Restricted data — are confirmed with the project lead.
• When in doubt, ask before using AI.
• Report incidents quickly to the lead. This is not about blame.

02 Working With AI Day-to-Day

Applies to every role — engineering, QA, design, PM, sales, ops.

03 Sensitive Data: Classify & Handle

The section that actually matters for a services company handling client code and data.

Can I put this into AI? A quick check

The four classes are the model; this is the in-the-moment version. Work top to bottom — the first match wins.

Four data classes

How we handle it in practice

• Secrets live in a secret manager — Vault, AWS/GCP Secrets Manager, Doppler, 1Password — never in code, chat, prompts, or tickets. Reference them via env at runtime.
• Keep secrets out of the repo — .env* in .gitignore, plus a committed .env.example with placeholder keys only.
• Redact before prompting — swap real names, keys, IDs, and hosts for placeholders; reproduce bugs with minimal synthetic data, not production dumps.
• Scan before commit — a pre-commit secret scanner (gitleaks, trufflehog, git-secrets) as a required hook so a key never reaches history in the first place.
• Turn off training/history on any tool touching Internal or above, and confirm a DPA is in place.
• Client terms win — a project's NDA or security addendum overrides this document. Check per project before pointing any AI at client work.
• Mind the format, not just the text — full production logs, real customer records, and screenshots or recordings can all carry secrets, PII, or client code. Redact or synthesise first.
• Unsure how to classify something? Ask a colleague or your lead before sending it to any AI tool.

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks   # blocks the commit if a secret pattern is found

04 Recommended & Restricted Tools

Our stance on categories. The maintained, named approved-tool list lives with AI Enablement.

05 Guardrails With Claude Code Hooks

Don't rely on discipline alone. Make the safe path the default by enforcing it in tooling. Two layers: permissions (declarative) and hooks (programmable).

The same principle applies beyond Claude Code — configure Cursor, Copilot, and internal agents so unsafe actions are blocked by default.

Layer 1 — deny access to secrets declaratively

The cheapest guardrail: tell Claude Code it may never read secret files. Add deny rules in .claude/settings.json (commit this so the whole team inherits it):

{
  "permissions": {
    "deny": [
      "Read(./.env)", "Read(./.env.*)",
      "Read(./secrets/**)", "Read(**/*.pem)", "Read(**/id_rsa*)"
    ]
  }
}

Layer 2 — enforce policy with hooks

Hooks run your own shell commands at defined points in the agent loop. Two we recommend: a PreToolUse hook that blocks risky actions before they run, and a PostToolUse hook that scans after edits. A PreToolUse hook that exits with code 2 denies the tool call and feeds its stderr back to Claude as the reason.

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command",
          "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-bash.sh" }] }
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [{ "type": "command",
          "command": "gitleaks protect --staged --no-banner || true" }] }
    ]
  }
}

#!/usr/bin/env bash
# Receives the tool call as JSON on stdin. Exit 2 = deny + return reason to Claude.
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // empty')

# Refuse to print or exfiltrate env/secret files
if echo "$cmd" | grep -Eq '(cat|less|head|tail|printenv|env).*(\.env|secret|credential|\.pem|id_rsa)'; then
  echo "Blocked: this command would expose secrets. Use the secret manager instead." >&2
  exit 2
fi

# Refuse obviously destructive commands
if echo "$cmd" | grep -Eq 'rm -rf (/|~|\$HOME)|git push .*--force.* (main|master)'; then
  echo "Blocked: destructive command. Run it manually if you truly intend to." >&2
  exit 2
fi

exit 0   # allow everything else

Layer 3 — scan for secrets, at every layer

A secret scanner reads diffs and files for high-entropy strings and known key formats (AWS, GCP, Stripe, private keys, and hundreds more) and fails when it finds one. Don't rely on a single choke point — run it wherever a secret could slip through:

• Pre-commit — the earliest, cheapest catch. Blocks the commit on the developer's machine before a secret ever reaches history. (See the gitleaks pre-commit example in Section 03.)
• CI / server-side — a pipeline job re-scans every push and PR, so a skipped or missing local hook doesn't become a leak. Fail the build on a hit.
• After every AI edit — the PostToolUse hook above runs gitleaks protect --staged right after the model writes code.
• Full-history audit — periodically scan the entire repo history (gitleaks detect), not just the latest diff, to catch anything already committed.

Common scanners, all open source and drop-in as a pre-commit or CI step:

• gitleaks — fast and widely used; pre-commit, CI, and protect mode for staged changes. Our default.
• trufflehog — verifies found secrets against the live provider to cut false positives.
• git-secrets — lightweight, AWS-focused; simple regex provider rules.

# fail if a secret is staged (use in a pre-commit / PostToolUse hook)
gitleaks protect --staged --redact --no-banner
# audit everything already committed
gitleaks detect --redact --no-banner

06 Developer Practices

Coding with assistants like Claude Code, Copilot, and Cursor.

Non-negotiables

• Understand before you commit. If you can't explain what a block does and why, it doesn't ship. No pasting generated code you haven't read into production.
• Review for security. Injection, missing validation, unsafe defaults, broken authz, weak crypto, secrets in code — AI reproduces insecure patterns from its training data.
• Verify dependencies are real. AI hallucinates package names; attackers pre-register them with malware ("slopsquatting"). Confirm the package, its maintainer, and download history before adding it.
• Watch licensing & IP. Generated code can mirror copyrighted or copyleft sources. Don't drop large verbatim blocks into client deliverables without knowing their origin.
• Own the tests. Don't let the model grade its own homework — review that tests exercise real behavior and edge cases, not just restate the implementation.
• Same PR review as everything else. AI-generated changes don't get a fast lane or special treatment.
• Watch the blind spots. Error handling, edge cases, and unnecessary complexity are where AI output most often falls short — review them explicitly.

How to review AI output

AI can sound confident even when it's wrong — review with that in mind.

Good fits vs. keep human-led

07 Runbook: Leaked Secrets & Rotation

A key ended up in a commit, a log, a prompt, or a screenshot. Here's exactly what to do — in order.

# 1. create the replacement
aws iam create-access-key --user-name svc-app
# 2. update it in the secret manager / deploy, verify the app is healthy
# 3. disable, confirm nothing breaks, then delete the old key
aws iam update-access-key --user-name svc-app --access-key-id AKIA_OLD --status Inactive
aws iam delete-access-key --user-name svc-app --access-key-id AKIA_OLD

# preferred: git-filter-repo
git filter-repo --path .env --invert-paths
# or BFG
bfg --delete-files .env && git reflog expire --expire=now --all && git gc --prune=now
git push --force --all

08 Legal, IP & Client Work

The parts that protect us and our clients.

09 Onboarding Checklist

First week for a new team member.

• Read this document. Focus on the four data classes and the leak runbook.
• Set up approved AI tools on your company account. Not a personal free tier — training/history off.
• Install the guardrails. Pull the shared .claude/settings.json deny-list + hooks and the pre-commit secret scanner.
• Confirm your project's AI rules. Ask your lead which tools the client permits and what's off-limits.
• Know what counts as Restricted data here. The project's hard no-AI boundary — re-check it on every new project.
• Know the leak drill. Save your security/lead contact so you can rotate and report fast.
• Verify your secret-manager access. Know where secrets live so you never hard-code or paste them.
• Join AI Enablement. Ask questions and propose new tools there.

PM Claude for PMs

Practice, not policy. Practical approaches and cases — short notes on how Claude can be used in a manager's daily work: where it helps most often, and where it lets you down. Everything above still applies.

Open as slides → Claude for PMs

1. What not to paste into AI

Three unread client messages, a follow-up to send after the morning call, and the reflex to paste the company name, the amount and what was discussed into your favourite AI tool. Stop for a second and ask yourself two questions.

• Whose data am I handing over right now? If it's my own thoughts and wording, it's safe. If it's client names, numbers or contacts, it isn't.
• What happens if the client accidentally sees this prompt tomorrow? If the answer is “that would be bad”, it shouldn't be shared with AI.

2. Why a skill may not work and how to avoid it

3. A skill is a feature too, and it needs testing

Imagine a skill not as a text instruction but as a full-blown feature. Nobody ships a feature to production after one lucky click: first it gets checked on different scenarios, edge cases and real data. Treat a skill the same way — take a few real requests, the kind you actually write at work, and check whether the skill responds to them consistently. It's QA, only not for code but for an AI skill.

Why does this matter especially for a manager? A skill in the team workspace immediately starts working for everyone. If it produces a bad result, that's already the whole team's problem. Testing catches it before the team does.

The loop: create the skill → test → see where it fell short → fix → test again. Take 3–5 real requests and run each one twice: with the skill and without it. Compare the results side by side, correct, and repeat until the result is stable and predictable.

4. Subagents: when one assistant becomes a team

When a decision is complex, it's worth gathering different perspectives — that's what a skill with subagents is for. Instead of one generic answer you get several experts who each examine the same decision from their own side, then converge into a comparison matrix and a recommendation.

Why a skill rather than a prompt in your notes? Copying such a bundle every time is inconvenient; a skill triggers itself. Write “evaluate the decision” and the multi-role breakdown starts right away.

• Take your working prompts and ask skill-creator to assemble a skill from them — say, decision-review: each subagent analyses the decision from its own side, then a matrix is compiled, and at the end there's a recommendation.
• Roles must be interchangeable — the skill shouldn't be stitched to the same experts forever.
• What matters most isn't the length of the instruction but the right description — that decides whether the subagents switch on by themselves.
• The file inside the folder must be named SKILL.md. Otherwise the system won't see the skill, and the subagents remain just a nice idea in a folder.

5. Subagent: parallel tasks

Turning a subagent into a whole team, where one searches, another writes, and a third checks. A subagent is a separate session that the main model spins up on its own: it gets a specific task, does its part and returns the result. It's easy to confuse with a skill, but a subagent is more like a freelancer — came, did the job, left. A skill is closer to a full-time employee.

• A subagent doesn't see the previous conversation. It starts from scratch and knows only what was passed to it, so “refine what we just discussed” almost never works. Give everything upfront: files, criteria and the expected format.
• It's launched with an ordinary prompt — “launch a subagent” or “launch three agents in parallel”. Before starting, the model usually shows a plan of who does what; that's where you can still adjust the breakdown.
• Good fit: parallel research, a fresh check of an already finished result, a breakdown of a large pack of documents, or several different roles on one task. On a short five-minute job it rather gets in the way — a subagent enters the topic from scratch every time.

6. Weak spots of subagents and why you need a verifier

• They're expensive. Each subagent is a separate session that re-reads the files and re-enters the topic, so three agents are almost like three full conversations. Launch them only when parallel work really saves time.
• A subagent doesn't ask back. If something is unclear, it won't stop — it will make an assumption and keep going.
• Subagents don't talk to each other. Only the main model brings everything together at the end. If parts of the task need to negotiate along the way, that's sequential work, not parallel.
• More agents doesn't mean a better result. Every new subagent is another retelling of the context and another place where something gets lost. The sweet spot is two to four.

When several agents work in parallel, it's harder to catch a mistake. This is where a verifier agent helps: one did the work, the other looks at it with fresh eyes, as if it were a colleague's draft. A model checking itself is already defending its own logic; the verifier didn't see how the answer was born, so it's more honest in its pushback. Run it before sending, after research with numbers, after several agents have worked — wherever a mistake is costly. Hallucinations most often hide in dates, prices and names.

Give it the right prompt, and don't tell it the text was written by AI — let it review it as a human's work, without leniency. Its job is to find questionable facts, gaps in logic and missed risks.

7. Google Docs templates without manual formatting

A large part of a manager's work is documents. The same font across eight files, identical headings, tidy metadata — exactly the kind of work you can hand over to AI. But for things to look right in Google Docs, a regular chat is often not enough: you need the Google Docs API. First authorise Google Drive, then grant Claude the access it asks for.

• Collect the templates in a Templates folder: Communication Plan, Meeting Notes, Project Brief, Retrospective, Risk Register, Stakeholder Register, Team & Roles, Weekly Status Report and whatever else the team actually uses.
• Don't go into each file — ask: “go through all of them and bring them to one look”. For example: Open Sans everywhere; document title large and green; section headings a bit smaller, also accented; date, time and participants lighter and in italics.
• Add one more request, without which the AI may get confused: “process the files one at a time and write down what's already done”.

8. Excalidraw + Claude: hand-drawn diagrams in minutes

The team needs a new process explained quickly. You can write a long message, or spend half an hour aligning blocks in Miro — or use Excalidraw: a digital whiteboard where everything looks hand-drawn. Just blocks, arrows and text; the team sees the picture right away instead of a wall of text, and it needs no learning.

It's especially handy when the case is complex and unusual: draw the main path, then add the “what if…” forks together with the team — on a diagram they become visible much faster than in text. It works just as well for architecture, dependencies between tasks or team structure.

You don't draw everything by hand — ask AI to draw your thoughts right inside Claude, with Excalidraw connected via a connector. There's no universal prompt: each time, spell out what exactly you're drawing (a process, a roadmap, team structure, a flow), which blocks or steps should be there, how they're connected, and how detailed it should be. The diagram isn't a static image — edit it by hand, or ask AI to look again and analyse exactly the points that matter.

9. Design review with Claude

Set up the Figma connector as usual: find Figma in the connector settings, log in and restart the session. The manager's job is to check the completeness of the screens and their compliance. After the review, three things should be clear: does the mockup solve the task we set, is everything development needs drawn, and has anything extra appeared that has neither an agreement nor a budget?

Giving it Figma links

• The page URL — to see the whole picture: how many screens, how they're grouped.
• A link to a specific frame — when you need to review states, texts, spacing, consistency.

AI can see and analyse screens, layer structure, tokens, library components, comments, sometimes even animations and FigJam. A prototype also works, with limitations: AI clicks on the image, sometimes misses, ends the session quickly on a long flow, and can't tell a prototype bug from intent. It won't feel that a screen is overloaded, but it also won't get lost where a real person would.

Combine several checks

• Compare the screens against the spec: what's not covered, what's extra, where they diverge.
• Separately go through states and edge cases.
• Separately check whether the screens “live” by the design system.
• Only then turn this — not into complaints, but into questions for the designer.

Where Claude gets it wrong

• It invents components — “there should be a Button/Primary here”, although the library has no such thing. Check the name before passing it on.
• Hidden layers — the state is drawn but sits under another frame; AI doesn't see it and says it's missing. Double-check before raising it.
• Large files — it may review 6 screens out of 20 and not mention it. Work in chunks and ask at the start: “how many screens did you actually see?”
• Generic UX advice — “add more white space”. Ignore it, or ask for specifics.
• A confident tone on assumptions — “email validation is missing”, when it may simply not have found it. Require it to mark such things as an “assumption”.
• It doesn't know your users and backend — it judges UX by general patterns and may fail to say “we simply don't have this data”. In prototypes, a non-clickable button could be a bug or intentional; it can't tell the difference.