Skip to content

feat(cli): add AGENTS.md to cdk init templates for TypeScript and JavaScript - #2125

Merged
kumvprat merged 2 commits into
aws:mainfrom
kumvprat:feat/cdk-init-agents-md
Nov 4, 2026
Merged

kumvprat merged 2 commits into
aws:mainfrom
kumvprat:feat/cdk-init-agents-md

Conversation

@kumvprat

@kumvprat kumvprat commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Fixes #

Summary

cdk init now writes an AGENTS.md file at the root of the TypeScript and JavaScript templates (app, sample-app, and lib for TypeScript). The file follows the agents.md convention, which many coding agents read automatically when they open a project. It tells the agent to read the AWS Construct Library docs that ship with the generated project before it writes constructs, and to read only the sections it needs.

Why

aws-cdk-lib ships a README with usage examples for every module (for example, node_modules/aws-cdk-lib/aws-s3/README.md). When an agent reads those docs before writing code, it tends to pick the right L2 construct, use grant methods such as bucket.grantRead(fn) instead of hand-writing IAM policies, and rely on the documented defaults. A short pointer file at the project root makes those docs discoverable, so the agent reads them instead of guessing.

There is precedent for shipping an AGENTS.md: both aws-cdk-cli and aws-cdk already ship contributor-facing AGENTS.md files (#1526, aws/aws-cdk#37666). This change extends the same convention to the projects that cdk init generates for users.

What the file contains

Each generated AGENTS.md has these sections:

Section Content
Project layout Where the code lives: the app entry point, the stack, and cdk.json (or the construct for lib).
Read the docs Run find node_modules/aws-cdk-lib -name README.md once. For each service the app uses, read its module README first and follow its patterns. List the README's headings with grep -n '^#', then read only the needed sections with sed -n '<start>,<end>p'.
Check your work The commands that apply to the template (build, test, synth, diff), with the right package manager.
More resources The AWS CDK Reference.

Why only TypeScript and JavaScript

These two languages get the module READMEs on disk under node_modules/aws-cdk-lib/<module>/README.md, so the file can point at real local files and the exact commands to read them. The other languages expose the docs in different ways (Python docstrings, go doc, Javadoc in a sources jar, .NET XML docs), so they are left for a follow-up once their guidance has been tried.

Design notes

  • Each template ships AGENTS.template.md because the "check your work" commands use the %pm-cmd% placeholder, so the init flow substitutes the right package-manager command.
  • The file is not injected into --from-path custom templates. Custom templates copy only the files physically present in the template directory, so a custom template gets an AGENTS.md only if its author adds one.
  • The lib/typescript template adds AGENTS.md to its .template.npmignore, so a published construct library does not ship the agent-guidance file.
  • No CLAUDE.md or other tool-specific files are added. The single AGENTS.md follows the shared convention, so it works across agents.

Testing

New cases in packages/aws-cdk/test/commands/init.test.ts:

  • For app and sample-app in typescript and javascript, plus lib typescript, assert the generated AGENTS.md exists, references aws-cdk-lib, includes the grep -n '^#' read-docs command, links the AWS CDK Reference, mentions the verification command, and has no leftover %placeholder%.
  • For app and sample-app in python, java, and go, assert no AGENTS.md is generated.
  • A --from-path custom template case asserts no AGENTS.md is injected.

Result with the .NET SDK on PATH: 105 passed, 105 total. Without the .NET SDK, the existing csharp/fsharp cases fail because their add-project hook shells out to dotnet; they fail on main too.

Manual test: I packed the CLI from this branch into an npm tarball (npm pack via the package task), installed it into a scratch folder, and ran cdk init with it:

Template AGENTS.md created
app typescript (full install) yes
app javascript yes
sample-app typescript yes
lib typescript yes
app python no

In the full app typescript project, the commands in AGENTS.md work as written: find node_modules/aws-cdk-lib -name README.md lists the module READMEs, grep -n '^#' lists a README's headings, and npm run build, npm test and cdk synth pass.

Checklist

  • This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed
    • Release notes for the new version:

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

@kumvprat
kumvprat requested a review from a team November 4, 2026 11:22
@github-actions github-actions Bot added the p2 label Nov 4, 2026
@maintainer-for-aws

maintainer-for-aws Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Automated review

A maintainer will still review this — treat the notes below as a starting point.

📌 Commit 85b03a2

This PR adds an AGENTS.template.md file to five built-in cdk init templates (app/javascript, app/typescript, sample-app/javascript, sample-app/typescript, and lib/typescript), guiding AI coding agents in freshly-generated CDK projects to read the on-disk module READMEs shipped with aws-cdk-lib before writing constructs. It also adds AGENTS.md to lib/typescript/.template.npmignore so published construct libraries don't ship the file, plus tests covering generation across languages and the --from-path path.

The change is additive and well-tested, with no change to init control flow or public surface. The template-processing mechanics are sound: each AGENTS.template.md is routed through placeholder expansion and renamed to AGENTS.md, the %pm-cmd% token expands correctly, and the new tests assert no unexpanded placeholder survives. The JavaScript variants correctly omit the build step, and the lib/typescript variant appropriately substitutes Template.fromStack(...) guidance for synth/diff. The "Check your work" commands match each template's actual package.json scripts, and the npmignore-versus-gitignore behavior is intended. No issues found on this change.

🔴 0 blocking · 🟡 0 recommended · ⚪ 0 optional


Generated automatically. React 👍 or 👎 to tell us whether this review helped, so we can improve these reviews.

@maintainer-for-aws maintainer-for-aws Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the review summary comment for the overview; the notes below are inline.

Comment on lines +1678 to +1679
expect(contents).toContain('https://docs.aws.amazon.com/cdk/api/');
// The rewritten read-docs section tells agents how to find and read service docs.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ Optional — The comment reads "The removed ## Traps section must not reappear," but none of the newly added AGENTS.template.md files ever contained a ## Traps section, so nothing was removed in this change. The comment narrates a history that did not happen here and could mislead the next reader into thinking a prior section was deleted. The assertion itself is a sound forward-looking regression guard; only the wording is inaccurate.

Suggested change: Reword the comment to describe the assertion as a forward-looking guard, e.g. "Guard against a ## Traps section being introduced in the future."

@codecov-commenter

codecov-commenter commented Nov 4, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.11%. Comparing base (15f90b4) to head (85b03a2).

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #2125      +/-   ##
==========================================
+ Coverage   92.08%   92.11%   +0.03%     
==========================================
  Files          83       83              
  Lines       13311    13311              
  Branches     1900     1902       +2     
==========================================
+ Hits        12257    12261       +4     
+ Misses       1016     1012       -4     
  Partials       38       38              
Flag Coverage Δ
suite.unit 92.11% <ø> (+0.03%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@kumvprat
kumvprat deployed to integ-approval November 4, 2026 11:40 — with GitHub Actions Active
@kumvprat
kumvprat enabled auto-merge November 4, 2026 12:11
@kumvprat
kumvprat added this pull request to the merge queue Nov 4, 2026
Merged via the queue into aws:main with commit 27c3e09 Nov 4, 2026
46 checks passed
@kumvprat
kumvprat deleted the feat/cdk-init-agents-md branch November 4, 2026 13:43

This branch had an error being deployed

1 failed (outdated), 1 active, and 1 inactive deployments
run-tests — 85b03a2d Deployed Nov 4, 2026 by kumvprat via integ_cli (cli-integ-tests, 24.19, 11) #7608
integ-approval — 85b03a2d Deployed Nov 4, 2026 by kumvprat via prepare #7608
automation — 670d9a65 Deployed Nov 4, 2026 by kumvprat via Set AutoQueue on PR #2125 #3935
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants