Working with Claude

This page is the team-shared operating contract for working with Claude (Cowork and Claude Code) in Adventive engineering. It is the same CLAUDE.md file that both tools read from the root of the repository, surfaced here so engineers can read it from the docs site.

If you change anything on this page, you are editing CLAUDE.md at the repo root. Both views update together — there is no separate copy.

CLAUDE.md — Adventive Platform Engineering

You are working in the Adventive Engineering documentation repository — the source of truth for docs.adventive.dev and the front door to all Adventive platform work (Cloudflare Workers, AWS, serverless). This file tells you how we work here.

Human engineers read this too. Both audiences are expected.

Operating principle for this file: point to the canonical doc, do not duplicate it. When facts in this file disagree with src/content/docs/platform/, the docs win — fix this file, not the docs.

1. Scope

This file governs:

This repository (adventive-engineering-docs) — plans, runbooks, ADRs, platform standards.
Cross-cutting rules that engineers and Claude carry into every Adventive code repository: adventive-platform-infra, adventive-public-api-worker, the admin dashboard, the status dashboard, the tools auth chain, and anything else under the Adventive GitHub org.

Each downstream code repository SHOULD have its own short CLAUDE.md at its root that points back here for cross-cutting rules and adds repo-specific context. A template lives at src/content/docs/_templates/repo-claude-md/CLAUDE.md.

2. Core principles

Existing patterns beat new ones. Before scaffolding any project’s infrastructure-as-code, CI/CD, secrets, or repo layout, check what already exists. A new parallel pattern is a defect, not a contribution.
SOPs are binding. Documents under src/content/docs/platform/ govern. Drift from them is a defect to fix, not a baseline to preserve.
Dev-only by default. Production and staging configuration is not yours to modify. Override requires an explicit human directive that meets the bar in §3.
Read the legacy before rewriting it. Open the legacy model and controller and match column names, field IDs, and behaviour character-for-character before writing the replacement.
Link, don’t duplicate. If a fact belongs in src/content/docs/platform/, put it there and link from this file. Encoding it twice creates drift.

3. Hard rules

These are non-negotiable. Violations are defects.

Do not modify pre-existing infrastructure settings. This includes any Terraform, Cloudflare, AWS, JumpCloud, or Cloudflare Access configuration that you did not create in the current session. Override is permitted only when the human issues a directive containing a literal ALERT banner, pauses 5 seconds, and confirms a second time.
Use the canonical Adventive infrastructure stack. Terraform modules live in adventive-platform-infra (NOT per-project). Deploys run from the local sandbox sourcing .cowork-env — NEVER from GitHub Actions. CI on PRs runs typecheck, lint, and unit tests only.
Honour every documented SOP. No silent deviation. Override requires explicit human direction plus an ADR citing the SOP section being overridden.
Read the legacy implementation before writing the rewrite. Open the legacy code first. Match identifiers exactly.
No passive-aggressive or personality-driven phrasing in engineering deliverables. Documentation is a professional artefact. Sweep tone before shipping.
Every shown shell command includes its working directory. Use cd <absolute-path> && <command> in fenced bash blocks AND in inline prose. No bare wrangler …, git …, or terraform ….
No # comments inside bash code blocks. They break zsh paste handling. Move explanation into surrounding prose.
Cloudflare Worker runtime secrets come from Cloudflare Secrets Store. Bind via [[secrets_store_secrets]] blocks in wrangler.toml referenced by store_id + secret_name. Never use wrangler secret put in committed scaffolds, runbooks, or CI flows — the whole point of Secrets Store is “create once at the account level, never paste again.” See src/content/docs/platform/cloudflare/workers/06-observability-opentelemetry.md for the canonical pattern.
Production deploys require AWS Secrets Manager IdP recovery codes provisioned. No --env prd deploy of any Worker, Pages site, or infrastructure module proceeds until the implementation checklist in src/content/docs/platform/aws/secrets-manager/01-idp-recovery.md §6 is complete and verified. Dev and stg are exempt; this gate applies only at prd promotion.
When an API write needs to be confirmed by an immediate read, use a bounded polling loop, not a manual re-issue. Retry every 1–2 seconds, stop on expected state, hard timeout 30 seconds. Surface the elapsed time on success or the most-recent partial response on timeout. Do not ask the user to manually re-run the read.
Log every override of a defined rule. When an individual directs an action that overrides any rule in this file, in CONTRIBUTING.md, or in a documented SOP, do all three before proceeding: (a) confirm the override with that person explicitly, naming the rule and the specific action; (b) record it in OVERRIDES.md (date, who authorized it, the rule overridden, what was done, and a concrete revert path); (c) proceed only after (a) and (b). This rule cannot itself be waived.

4. Where things live

Repositories

What	Location
Engineering documentation (this repo)	`~/Repositories/GitHub/Adventive/adventive-engineering-docs/`
Cloudflare-touching IaC (Terraform)	`~/Repositories/GitHub/Adventive/adventive-platform-infra/`
Public API Worker	`~/Repositories/GitHub/Adventive/adventive-public-api-worker/`
Local dev toolkit for the Public API	embedded scripts: `bootstrap`, `dev-up`, `dev-deploy`, `dev-down`, `doctor` (macOS-only)

Inside this repo

What	Path
Cross-project platform standards	`src/content/docs/platform/`
Cloudflare patterns (Workers, Tunnel, Access, DNS)	`src/content/docs/platform/cloudflare/`
Observability standard (OTel → New Relic) + Secrets Store binding pattern	`src/content/docs/platform/cloudflare/workers/06-observability-opentelemetry.md`
AWS patterns (Secrets Manager and future services)	`src/content/docs/platform/aws/`
AWS Secrets Manager IdP recovery (production gate)	`src/content/docs/platform/aws/secrets-manager/01-idp-recovery.md`
PDF house style	`src/content/docs/_templates/STYLE.md`
New-project skeleton	`src/content/docs/_templates/project-skeleton/`
Downstream-repo CLAUDE.md template	`src/content/docs/_templates/repo-claude-md/CLAUDE.md`
Per-project work (one folder each)	`src/content/docs/projects/<kebab-case>/`
Superseded content (excluded from site)	`src/content/docs/_archive/`
Shared design tokens (excluded from site)	`src/content/docs/_shared/`
Proposals under review (excluded from site)	`src/content/docs/_proposed/`

Environments → DNS zones

Environment	Zone
Production	`adventive.com`
Staging	`adventivestg.com`
Development	`adventive.dev`
Internal staff tools hub	`adventive.io`

Platforms

Concern	Platform
Application performance monitoring	New Relic (see §5 — OTel baseline)
Identity (SSO)	JumpCloud SAML
MFA	Duo
Edge compute	Cloudflare Workers
Edge storage	Cloudflare D1, KV, R2
Static hosting	Cloudflare Pages
Private network	Cloudflare Tunnel
Access policy	Cloudflare Access
Cloudflare Worker runtime secrets	Cloudflare Secrets Store (bound by reference; see hard rule §3.8)
IdP recovery codes (JumpCloud, Google, Duo)	AWS Secrets Manager — `adventive-idp-recovery-*` namespace, `AdventiveIdPRecoveryReader` IAM role, MFA-gated (see hard rule §3.9 and `src/content/docs/platform/aws/secrets-manager/01-idp-recovery.md`)
AWS-platform runtime secrets (Cognito, S3, EC2/SSM, Mailgun-via-AWS)	AWS Secrets Manager / Parameter Store

Cloudflare documentation

Fetch directly from these authoritative URLs before designing or troubleshooting. Do not rely on training data for Cloudflare specifics — the platform moves quickly. The canonical pointer list lives at src/content/docs/platform/cloudflare/README.md.

5. Engineering practice

Starting a new project (documentation)

cd ~/Repositories/GitHub/Adventive/adventive-engineering-docs && cp -R src/content/docs/_templates/project-skeleton src/content/docs/projects/<kebab-case-name>

Fill in the skeleton in order: 00-context.md, 01-architecture-assessment.md, 02-code-updates.md, 03-deployment-management.md, 04-runbook.md, 05-appendix.md. Add the project to the sidebar array in astro.config.mjs to surface it in the nav (Starlight has no .pages equivalent; the sidebar is declared in config).

Starting a new code project

For any new code project (Worker, service, app):

Repository analysis — read the legacy or adjacent code first (see hard rule 4).
Serverless-viability assessment — Cloudflare Workers first. Justify any move off Workers in an ADR.
Produce the full GDSC-pattern deliverable set — numbered chapters (00-context through 05-appendix), a WeasyPrint PDF, and a handoff/ directory for handoff documents (kickoff briefs, status updates).
Place all of the above in src/content/docs/projects/<kebab-case>/ within this repo before any code is written.

Architecture Decision Records (ADRs)

cd ~/Repositories/GitHub/Adventive/adventive-engineering-docs && touch src/content/docs/projects/<project>/decisions/$(date +%F)-<short-slug>.md

Link the new ADR from the project’s 05-appendix.md. ADRs are append-only — supersede, do not edit.

Producing engineering PDFs

WeasyPrint HTML/CSS only. Do not use Quartz, macOS Print-to-PDF, or LibreOffice. Reference an existing project’s build_pdf.py as your starting point. Do not modify the CSS in src/content/docs/_templates/STYLE.md without a written reason.

Output filename:

Adventive_<Project>_<DocType>.pdf

Cloudflare design pillars (mandatory)

Every Cloudflare planning or design deliverable MUST address all six pillars. Missing a pillar is a defect.

Redundancy — what fails over when an instance/region/edge dies?
Resiliency — how does the system degrade under partial failure?
Disaster recovery — RTO/RPO targets and the procedure that meets them.
Backup — what is backed up, where, how often, and how it’s restored.
Deployment — release flow, rollback, environment promotion.
Observability — telemetry, alerting, dashboards. See OTel baseline below.

Observability — OpenTelemetry → New Relic

Mandatory baseline for every Worker and every Pages SPA. The canonical implementation reference is src/content/docs/platform/cloudflare/workers/06-observability-opentelemetry.md.

Library: @microlabs/otel-cf-workers
Endpoint: https://otlp.nr-data.net:4318
Toggle: a single OTEL_ENABLED environment variable per Worker.
Defaults: dev false, stg true, prd true. POC carve-out: dev true until both POC repos verify the pipeline.
Secret: NEW_RELIC_LICENSE_KEY is bound from Cloudflare Secrets Store per env (new-relic-license-key-dev/-stg/-prd) via a [[secrets_store_secrets]] block in wrangler.toml. Read at runtime via await env.NEW_RELIC_LICENSE_KEY.get(). Never wrangler secret put — see hard rule §3.8.

Secret storage

Cloudflare Worker runtime secrets → Cloudflare Secrets Store (account-scoped, bind by reference). See src/content/docs/platform/cloudflare/workers/06-observability-opentelemetry.md for the canonical binding pattern (the NR ingest key is the worked example; the same pattern applies to every other Worker-bound secret).
IdP recovery codes (JumpCloud SAML metadata, Google OIDC client credentials, Duo integration key) → AWS Secrets Manager under the adventive-idp-recovery-* namespace, gated by the AdventiveIdPRecoveryReader IAM role with MFA + 15-minute MFA freshness. Out-of-band from Cloudflare to avoid the circular dependency at DR time. See src/content/docs/platform/aws/secrets-manager/01-idp-recovery.md — currently a stub; implementation is the production gate per hard rule §3.9.
AWS-platform runtime secrets (Cognito, S3, EC2/SSM, Mailgun-via-AWS-config) → AWS Secrets Manager / Parameter Store, existing pattern.

Adventive does not use 1Password. If a runbook or scaffold references “1Password,” that’s stale text — fix it in the same PR you touch the file.

Cloudflare Tunnel infra pattern

Standing pattern, do not invent alternatives:

Image Builder produces the tunnel host AMI.
Auto Scaling Group runs the tunnel instances.
One tunnel per environment (dev/stg/prd).
Replica HA inside each environment.
Rolling updates achieve zero-downtime tunnel restarts.

Pre-prd hardening required: NAT gateway + private-subnet placement for tunnel hosts (currently public-subnet + SG-only isolation in dev).

Sandbox cloud workflow

Cloudflare API calls and wrangler deploy execute from a local sandbox that sources a .cowork-env file for credentials. Deploys never run from GitHub Actions. The engineer’s local sandbox configuration (paths, npm scratch directory, mount-unlink quirk on macOS) is captured in each engineer’s local environment notes — refer to the engineer’s onboarding doc rather than encoding paths here.

Tooling expected on PATH for cloud commands: wrangler, terraform, gh, cloudflared.

Worker custom hostnames

Every custom hostname requires a proxied AAAA record at 100:: to exist before the Worker is deployed to that route. Pre-create the record; otherwise the first request 1014s.

MySQL on Cloudflare Workers

The mysql2 driver requires disableEval: true in its configuration object. Workers blocks eval and new Function; the default driver path uses both. Pass the full config as an object, not a connection string.

6. Output conventions

When you produce text the user will read or paste:

Commands include their working directory. cd <absolute-path> && <command> in every fenced bash block AND in inline prose. No bare commands.
No # comments inside bash code blocks. They break zsh paste handling. Use surrounding prose instead.
Professional tone. No personality-driven asides. No “ask and copy what they did.” No “stop being the bottleneck.” Engineering deliverables describe the work, not the team.
Match the PDF style exactly when producing engineering PDFs. The style is the contract; deviations require a written reason.
Adventive__.pdf is the filename convention.

7. Workflow contract — how to operate in this repo

Pre-flight every new project. Before generating IaC, CI/CD, secrets, or repo layout, stop and check the matching SOP under src/content/docs/platform/. The defaults listed in §4 (Terraform → adventive-platform-infra, deploys → sandbox, CI → typecheck/lint/test) are not suggestions.
Read existing infrastructure freely. Modify it only on explicit override. The hard rule in §3.1 covers what counts as override.
Mount the right folder. When the user asks you to edit something outside the current Cowork mount, request the folder via the Cowork directory tool rather than dictating manual edits to them.
Concurrent sessions in one working tree. Two Claude sessions operating in the same working directory will stash or clobber each other’s uncommitted work (branch switches stash the dirty tree). If proceeding would put a second session in a checkout another session is already using, alert the operator and ask how to proceed before touching the shared tree; prefer an isolated git worktree. Exception: if this session initiated the parallel work itself, that is safe, so continue without alerting.
Link, don’t duplicate. When you find yourself encoding a fact into this file, ask whether it belongs under src/content/docs/platform/ instead. Put it there, link from here.
Memory layering. Team-shared rules live in this file and under src/content/docs/. Personal preferences (nicknames, local paths, in-flight project state, your own past mistakes) live in each engineer’s local Claude memory. Never promote personal context into team docs without abstracting first.
When a rule conflicts with itself. This file is younger than the codebase. If you find this file disagreeing with how the team actually works, that is the bug. Open a PR against this file.

8. For human engineers reading this

This file is Claude’s working contract — but it is also your statement of how the team builds. Two practical notes:

If you want Claude to behave differently across the whole team, change this file via PR. Local-memory tweaks affect only you.
If a rule here turns out to be wrong, fix it the same way you’d fix a broken test: PR with explanation.

The Astro Starlight site at docs.adventive.dev surfaces this file under “Working with Claude” so the same content is readable from the docs UI.

9. Cross-references

House style for engineering PDFs: src/content/docs/_templates/STYLE.md
Project skeleton: src/content/docs/_templates/project-skeleton/
Downstream-repo CLAUDE.md template: src/content/docs/_templates/repo-claude-md/CLAUDE.md
OTel → New Relic standard: src/content/docs/platform/cloudflare/workers/06-observability-opentelemetry.md
Cloudflare platform reference list: src/content/docs/platform/cloudflare/README.md
Site landing page: src/content/docs/index.md
Repo landing page: README.md