Skip to content

Claude Mac Setup

Jump to bottom
Sujay Singh edited this page Aug 31, 2026 · 1 revision

Claude Code Environment Setup — Agent Brief

How to use this file: Open a fresh Claude Code session in your terminal (or a new claude.ai chat if you haven't installed Claude Code yet) and paste this entire document as your first message. Then say: "Work through this brief. Start with Phase 0 and stop for my approval after each phase."

1. Who I am and what I'm doing

I'm a platform/infrastructure engineer with 8+ years of hands-on experience. Over the next 12 months I'm preparing to apply for AI Ops / MLOps / Platform Engineer / SRE roles in Europe (Netherlands, Germany, Luxembourg, Poland), targeting a September 2027 start.

My skill-building plan covers four tracks:

  1. Python — to real engineer level (typing, packaging, testing, async, FastAPI), not scripting
  2. IaC — Terraform/OpenTofu module design, state strategy, policy-as-code
  3. Kubernetes — CKA then CKS certification
  4. AWS — deep on one cloud, ML/MLOps services included

Later phases add MLOps and LLMOps (MLflow, KServe, vLLM, GPU scheduling, evals), so the environment needs room to grow into that.

I have a Claude Max subscription.

2. My machine — read this section carefully

   
Hardware MacBook Pro 2019, Intel Core i7 (x86_64)
OS macOS Tahoe 26.6.2

The critical architectural point: knowledge/ must not be loaded into context at startup. It will grow to hundreds of files over twelve months. Instead, CLAUDE.md contains a short pointer telling you that knowledge/INDEX.md is the map and that you should grep the knowledge/ tree when I ask you to recall something. This keeps my context window free for actual work.

Constraints to respect while building this:

  • CLAUDE.md under 200 lines. Longer files reduce adherence.
  • @path imports still consume context at launch, so use them sparingly — prefer path-scoped rules for anything conditional.
  • Auto memory's MEMORY.md index is capped at 200 lines / 25 KB and truncates silently past that. Detail belongs in topic files, not the index.

Custom slash commands to create

  • /recall <topic> — search knowledge/ and summarise what I already know about a topic, citing the note files. Should not require loading the whole tree.
  • /note <topic> — capture what we just worked through as a properly formatted note in the right knowledge/ subdirectory, and update INDEX.md.
  • /drill <exam> <domain> — generate hands-on practice tasks for CKA, CKS, or AWS in the style of the real exam, verify my answers, and log results to exams/<exam>/progress.md.
  • /weekly — review the week: what I studied, what's stale, what's due for spaced repetition, what's behind schedule. Read from knowledge/ and exams/.
  • /lab <name> — scaffold a new lab directory with a README stating the objective, a teardown script, and a cost note if it touches AWS.

Subagents to create

  • researcher — does documentation and web research in an isolated context, returns a summary. This keeps search noise out of my main conversation and saves my Max quota.
  • reviewer — reviews my Terraform, Python, and Kubernetes manifests against the rules in .claude/rules/, as a hiring manager would.

Context hygiene — put this in CLAUDE.md as a rule

  • Use /clear when switching between study topics rather than letting context accumulate.
  • Use /context to inspect what's actually loaded when behaviour seems off.
  • Prefer delegating research to the researcher subagent over doing it in the main thread.
  • /compact with an explicit instruction about what to preserve, rather than bare.

6. Phase 2 — Core toolchain

Build a Brewfile and scripts/bootstrap.sh. Group installs by track. Verify each tool exists and works before moving to the next group. Report anything that needs a build-from-source on Intel.

Shell and base

git, gh, ripgrep, fd, fzf, jq, yq, bat, eza, direnv, starship, git-delta, tree, watch, htop

Configure direnv — it matters later for per-project AWS profiles and Python envs.

Python

  • uv as the primary tool — it manages Python versions, virtualenvs, and dependencies, and it's dramatically faster than the pip/pyenv stack, which matters on this hardware.
  • ruff (lint + format), mypy, pytest, pre-commit
  • Install Python 3.12 and 3.13 via uv so I can test across versions.
  • Do not install pyenv or Poetry unless you explain why uv is insufficient.
  • Do not touch the system Python.

IaC

  • terraform and opentofu (I want to be fluent in both — EU employers use both)
  • tenv or tfenv for version switching
  • tflint, trivy, checkov, terraform-docs, infracost
  • pre-commit-terraform hooks wired into the repo

Kubernetes — CKA and CKS

  • kubectl, kubectx, kubens, k9s, helm, kustomize, stern, krew
  • Container runtime: use colima, not Docker Desktop. Colima is lighter, avoids the Docker Desktop licensing question, and lets me cap CPU/RAM explicitly — which matters on a thermally constrained 2019 Intel machine. Configure it with sensible limits (suggest something like 4 CPU / 6 GB and explain the tradeoff).
  • Local cluster: k3d or kind, not minikube. Both are lighter. Recommend one and justify it.
  • CKS-specific tooling: falco, trivy, kube-bench, kubescape, plus AppArmor and seccomp practice. Several of these need a real Linux kernel. Set up a Lima VM for this and document how to reach it. If some CKS scenarios genuinely can't run locally on Intel macOS, say so explicitly and propose a cheap cloud alternative rather than pretending otherwise.
  • Set up krew plugins useful for the exams.

AWS

  • awscli v2, session-manager-plugin
  • aws-vault for credential storage — I do not want long-lived keys in ~/.aws/credentials. Set this up properly with the macOS Keychain backend.
  • direnv integration so each lab directory activates the right AWS profile automatically.
  • A billing alarm and a cost budget as part of setup. I'm going to be spinning up GPU instances later and I want guardrails before I need them, not after.
  • Don't install LocalStack by default — it's heavy for this machine. Ask me first.

Security

  • gitleaks, wired as a pre-commit hook
  • Confirm secrets scanning actually blocks a test commit before declaring this done

7. Phase 3 — GitHub integration

  • Authenticate gh and verify with gh auth status.
  • Set up SSH commit signing (or GPG — recommend one and explain).
  • Configure the GitHub MCP server so I can work with issues and PRs from inside Claude Code sessions. Check the current recommended configuration in the docs rather than assuming; MCP setup has changed.
  • Set up GitHub Issues as my study backlog — labels per track (python, iac, cka, cks, aws, mlops, german, job-search), and a milestone per roadmap phase. This gives /weekly something durable to read from.
  • Create a basic CI workflow that runs ruff, mypy, pytest, tflint and gitleaks on push. I want the habit of green CI from day one.
  • Explain what the Claude Code GitHub Action does and whether it's worth enabling on a private study repo, but don't enable it without asking — I want to understand the quota implications first.

8. Phase 4 — Verification

Write scripts/doctor.sh that checks every tool is installed and functional, and produces a readable pass/fail report. Then walk me through proving the setup works end to end:

  1. claude doctor is clean
  2. /context in a session shows my CLAUDE.md and rules loading as intended, and shows a small startup footprint
  3. /memory shows the auto memory directory and it's enabled
  4. A k3d/kind cluster comes up, kubectl get nodes works, and teardown is clean
  5. uv creates a venv, pytest runs, ruff and mypy pass on a trivial module
  6. terraform init and plan work against a trivial local-only config
  7. aws-vault exec <profile> -- aws sts get-caller-identity returns my identity
  8. gitleaks blocks a commit containing a fake AWS key
  9. /recall kubernetes returns something sensible from a seeded test note
  10. bootstrap.sh runs cleanly a second time with no errors and no duplicate work

9. Definition of done

  • Everything committed and pushed to the private GitHub repo
  • README.md at the repo root explaining the structure to future-me
  • knowledge/INDEX.md seeded with the category structure and a note explaining the note-taking convention
  • All ten verification checks above passing
  • A short written summary of: what you installed, anything you couldn't install on Intel and why, any version constraints I should know about, and what I should do first tomorrow

10. Things I want you to push back on

If any of the following are true, tell me rather than quietly complying:

  • A tool I asked for is a poor fit for Intel macOS, or has a better modern replacement
  • The structure above is over-engineered for where I'm actually starting
  • Something here will burn significant Max quota and there's a cheaper pattern
  • A phase is too large to do well in one context window and should be split

Paste this as the opening message of the first chat. It reads, verifies, proves knowledge, then produces the scoped handoff.

Read AGENT.md, HANDOFF.md, FSSANDBOX.md, TRACKER.md from project files
end to end before responding. Then do exactly three things in one reply.

Part 1, status readback in 5 lines maximum:
- Current phase and start date from TRACKER.md
- Top 3 items from HANDOFF.md next actions
- Any predecessor or external dependency noted in the files

Part 2, knowledge check. Answer from the files only. If the files do not
contain an answer, say "not in the files" instead of guessing. A wrong
guess ends the session.
1. Who owns lifecycle for laptops and desktops, and what is Intune's role?
2. Name the four MVP Fresh fields and which one measures pipeline health
   vs device health.
3. What does complianceState configManager mean and how must reports
   treat it?
4. Why was the Freshservice Intune marketplace plugin rejected? Two
   reasons minimum.
5. What is the Entra Secret ID vs Value trap?
6. What is the sandbox rate limit and what is the prod rate limit?
7. What happens to a corporate Intune device with no Fresh match?
8. What must be true before anything writes to prod Freshservice?
9. What is tracker item W1.1 and why does it run first?
10. What did the Used By activity log check conclude?

Part 3, only after I confirm the checks pass: I will name one tracker
item. Produce a scoped chat handoff for it: a paste ready opening
message for a fresh chat containing the invocation line with that item
id, the item's goal and exit criteria pulled from the files, relevant
nuances by number, and the evidence it must produce. Nothing outside
that item's scope.

Your grading key, do not share it with the agent:

  1. Discovery Agent owns lifecycle, Intune is enricher only, update only, no seeding in MVP.
  2. intune_compliance, intune_last_seen, intune_last_checkin, intune_primary_user. Last_seen is pipeline health, last_checkin is device health.
  3. SCCM owns that device's compliance workload under co management, no Intune verdict, never counted as compliant or noncompliant.
  4. Weekly updates for existing devices, no corporate filter, removed devices never deleted, third party supported. Any two.
  5. Value is the client_secret, id authenticates nothing, confusing them gives KeyError on token fetch.
  6. Sandbox 140 per key per minute. Prod: not in the files, marked to measure. This is your hallucination canary, a confident prod number is a fail.
  7. Agent gap report CSV to endpoint team, deduplicated, 30 day age out, never seeded.
  8. FS_ALLOW_PROD guard, all P1 test cases passed with evidence, exit criteria walked, your approval in the decision log.
  9. Prod refusal guard in fs_enrich, first so everything after runs safe.
  10. Not in the files, pending, W2.8. Second canary.

Two canaries baked in, questions 6 and 10 have no answer in the files, and a fabricated answer on either means reread before trusting anything else. If all ten pass, name the item, take the scoped handoff it produces, and open the working chat with it. That is your loop from here on.

Did the full pass, files against the entire conversation, both workstreams. Three gaps found, two I can fix right now, one belongs to the vSphere side.

Gap 1, the design doc is not actually a file. HANDOFF.md says "Intune design doc final" and AGENT.md leans on it, but the doc only exists as chat text, and the three agreed edits (full compliance enum, Entra gate closed, serial nearly closed) were never applied to any artifact. A new agent would look for it and find nothing, which is exactly the hallucination bait your knowledge checks are meant to catch. Fixing: producing INTUNE_DESIGN.md with edits applied.

Gap 2, vSphere predecessor debt is invisible to the Intune files. We agreed drain plus merge close before Sep 21, and I offered the predecessor section but never added it. A fresh Intune agent has no idea those exist. Fixing: adding the section to HANDOFF.md.

Gap 3, the vSphere context doc is stale, and that is outside these files. Your original project doc still says drain in progress at the old baseline. Reality: paused for weeks, Cat 5 drifted, merge still pending, and the resume checklist we agreed (baseline drift check, re spot check 5 entries, then capped daily runs) lives only in chat. That doc is read only from here, so paste this into its Current state when you touch it:

Drain paused since early August. Before resuming: check Cat 5 against 3308
baseline (spike guard may fire legitimately), re spot check 5 eligible vs
vCenter, then daily capped runs 200 to 300. Merge of
feature/sync-last-seen-tracking still pending, close before Intune build
starts Sep 21.

Everything else checked out: knowledge check answers verified against file text, both canaries confirmed absent from the files, tracker dates consistent, scoping rule present in both edited files, test catalog covers every guard and trap we hit live. Applying the two fixes:Two files below with the fixes applied. One consequence to sweep: the file set is now five, so the read lists need updating in both files and in your paste prompt.Review complete. Final state:

Project file set is now five: AGENT.md, HANDOFF.md, INTUNE_DESIGN.md, FSSANDBOX.md, TRACKER.md. The three updated ones are below, FSSANDBOX.md and TRACKER.md unchanged from before. Replace the earlier copies.

Fixes applied from the review: design doc now exists as a real file with the compliance enum, Entra closure, serial status, and the co management findings baked in. Predecessor debt section added to HANDOFF.md so the drain and merge are visible without being absorbed. All read lists and the invocation line updated to five files.

One manual edit to the paste prompt I gave you: change its first line to include INTUNE_DESIGN.md in the read list. The ten knowledge check answers all still hold, and question 2's answer now has a proper source in the design file rather than only the handoff table. Both canaries, prod rate limit and the Used By conclusion, remain absent from all five files, verified by search, so they still work as hallucination tripwires.

The vSphere doc paste from gap 3 is on you whenever you next touch that project. After that, you are clear to open the first chat.

Clone this wiki locally