anthropic-on-aws
CLAUDE.md443 starsChanged 3 months agoMIT-0View on GitHub
Guidance for Claude Code (and humans) contributing to aws-samples/anthropic-on-aws. Subprojects with their own CLAUDE.md (e.g. claude-apps-gateway/) take precedence for work inside them; this file covers the repo as a whole. A collection of independent samples, notebooks and workshops for using Anthropic's Claude on AWS. Each top-level directory is its own project with its own README, stack, dependencies and lifecycle. There is no shared library and no root build that exercises the samples. - notebooks/ — model getting-started guides (claude_<model>_getting_started/) and…
In this repository3 other files it gives its agents.
- advanced-claude-code-patterns/CLAUDE.mdCLAUDE.md
- claude-apps-gateway/CLAUDE.mdCLAUDE.md
- claude-platform-on-awsSkill
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
One subproject per PR: Don't touch other directories, and don't reformat files you aren't changing.
- Very specific: line 42
Model IDs: use Bedrock model IDs and inference profiles (global., or a geo prefix such as us./eu./au.).
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Guidance for Claude Code (and humans) contributing to aws-samples/anthropic-on-aws.
Subprojects with their own CLAUDE.md (e.g. claude-apps-gateway/) take precedence
for work inside them; this file covers the repo as a whole.
What this repo is
A collection of independent samples, notebooks and workshops for using Anthropic's Claude on AWS. Each top-level directory is its own project with its own README, stack, dependencies and lifecycle. There is no shared library and no root build that exercises the samples.
notebooks/— model getting-started guides (claude_<model>_getting_started/) and feature notebooks. One notebook per directory.cookbooks/— focused recipes.- Other top-level dirs — deployable demos (CDK, Lambda, AgentCore, Streamlit, Next.js).
docs/+mkdocs.yml— the GitHub Pages site, published on every push tomain..claude/skills/— Claude Code skills shipped as samples (they are content, not repo tooling).
Ground rules
- One subproject per PR. Don't touch other directories, and don't reformat files you aren't changing. Cross-cutting changes (CI, root docs) go in their own PR.
- A human reviews and merges every PR (aws-samples policy). Mergify is installed but
deliberately inert (
.mergify.yml); don't add rules or auto-merge. - Teach the supported path. Samples look authoritative, so prefer documented
Anthropic and AWS behavior over workarounds, and link the official docs instead of
restating API behavior that will go stale. See the 1p-first guardrails in
claude-apps-gateway/CLAUDE.md; they apply in spirit repo-wide. - Never commit secrets, AWS account IDs, real ARNs, internal hostnames, customer
data, or notebook outputs that contain any of these. Use placeholders such as
123456789012andexample.com. - License is MIT-0. Don't add third-party code with an incompatible license.
Conventions
- Commit and PR titles: Conventional Commits, scoped to the subproject directory:
fix(claude-apps-gateway): …,docs(notebooks): …,chore(deps): …. Explain why in the body; reference the issue (Fixes #N) when there is one. - Model IDs: use Bedrock model IDs and inference profiles (
global., or a geo prefix such asus./eu./au.). Prefixes differ by model and region, so check the current Bedrock inference-profile docs rather than copying from an older sample. - New model getting-started notebook: copy the structure of the newest
notebooks/claude_*_getting_started/directory, name itclaude_<family>_<major>_<minor>_getting_started/claude-<family>-<major>-<minor>-getting-started.ipynb, and clear outputs that contain account-specific data before committing. - New subproject: include a README (prereqs, deploy, cleanup, cost note), list it in
the root
README.md, and add it tomkdocs.yml/docs/if it should appear on the site. - Dependencies: pin them in the subproject's own lockfile/requirements. Dependabot
is security-only and grouped (
.github/dependabot.yml); don't add routine version-bump configs. - GitHub Actions: pin third-party actions to a full commit SHA with a
# vX.Y.Zcomment, matching.github/workflows/.
Verification
Root CI (build workflow) only packs the repo and fails if the build changes tracked
files. It does not test your sample, so verify locally before opening a PR:
- Notebooks: run top to bottom against Bedrock in a clean kernel.
- CDK:
cdk synth(and deploy + destroy if you changed resources). - Subprojects with tests/scripts: run them (e.g.
claude-apps-gateway/test/*.sh). - Docs site changes:
mkdocs build(see.github/workflows/docbuild.ymlfor plugins).
State what you ran in the PR description.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

