Repository navigation
feat(cli): add AGENTS.md to cdk init templates for TypeScript and JavaScript - #2125
Conversation
|
Automated review A maintainer will still review this — treat the notes below as a starting point. 📌 Commit This PR adds an The change is additive and well-tested, with no change to init control flow or public surface. The template-processing mechanics are sound: each 🔴 0 blocking · 🟡 0 recommended · ⚪ 0 optional Generated automatically. React 👍 or 👎 to tell us whether this review helped, so we can improve these reviews. |
There was a problem hiding this comment.
See the review summary comment for the overview; the notes below are inline.
| expect(contents).toContain('https://docs.aws.amazon.com/cdk/api/'); | ||
| // The rewritten read-docs section tells agents how to find and read service docs. |
There was a problem hiding this comment.
⚪ 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 Report✅ All modified and coverable lines are covered by tests. 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
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Fixes #
Summary
cdk initnow writes anAGENTS.mdfile at the root of the TypeScript and JavaScript templates (app,sample-app, andlibfor 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-libships 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 asbucket.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: bothaws-cdk-cliandaws-cdkalready ship contributor-facingAGENTS.mdfiles (#1526, aws/aws-cdk#37666). This change extends the same convention to the projects thatcdk initgenerates for users.What the file contains
Each generated
AGENTS.mdhas these sections:cdk.json(or the construct forlib).find node_modules/aws-cdk-lib -name README.mdonce. For each service the app uses, read its module README first and follow its patterns. List the README's headings withgrep -n '^#', then read only the needed sections withsed -n '<start>,<end>p'.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
AGENTS.template.mdbecause the "check your work" commands use the%pm-cmd%placeholder, so the init flow substitutes the right package-manager command.--from-pathcustom templates. Custom templates copy only the files physically present in the template directory, so a custom template gets anAGENTS.mdonly if its author adds one.lib/typescripttemplate addsAGENTS.mdto its.template.npmignore, so a published construct library does not ship the agent-guidance file.CLAUDE.mdor other tool-specific files are added. The singleAGENTS.mdfollows the shared convention, so it works across agents.Testing
New cases in
packages/aws-cdk/test/commands/init.test.ts:appandsample-appin typescript and javascript, pluslibtypescript, assert the generatedAGENTS.mdexists, referencesaws-cdk-lib, includes thegrep -n '^#'read-docs command, links the AWS CDK Reference, mentions the verification command, and has no leftover%placeholder%.appandsample-appin python, java, and go, assert noAGENTS.mdis generated.--from-pathcustom template case asserts noAGENTS.mdis 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 todotnet; they fail onmaintoo.Manual test: I packed the CLI from this branch into an npm tarball (
npm packvia thepackagetask), installed it into a scratch folder, and rancdk initwith it:AGENTS.mdcreatedapptypescript (full install)appjavascriptsample-apptypescriptlibtypescriptapppythonIn the full
apptypescript project, the commands inAGENTS.mdwork as written:find node_modules/aws-cdk-lib -name README.mdlists the module READMEs,grep -n '^#'lists a README's headings, andnpm run build,npm testandcdk synthpass.Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license