diff --git a/packages/aws-cdk/lib/init-templates/app/javascript/AGENTS.template.md b/packages/aws-cdk/lib/init-templates/app/javascript/AGENTS.template.md new file mode 100644 index 000000000..27af43dac --- /dev/null +++ b/packages/aws-cdk/lib/init-templates/app/javascript/AGENTS.template.md @@ -0,0 +1,38 @@ +# AGENTS.md + +This is an AWS CDK app written in JavaScript. The app entry point is the file in +`bin/` that creates the `App`; the stack is defined in `lib/` (the `*-stack.js` +file). `cdk.json` tells the CDK Toolkit how to run the app. + +## Read the construct library docs before writing code + +AWS CDK service documentation ships inside the aws-cdk-lib package. After you +install dependencies with `npm install` (so `node_modules/aws-cdk-lib` exists) +and before you write your CDK constructs, find the service READMEs once: + +``` +find node_modules/aws-cdk-lib -name README.md +``` + +For each AWS service you use in this app, read that service's module README (for +example, `node_modules/aws-cdk-lib/aws-s3/README.md`) first and follow its +documented construct usage and patterns. Not every service has a README; a +missing one is not an error. Read the relevant READMEs before writing the +constructs for each service. + +Before reading a service README, list its section headings with +`grep -n '^#' node_modules/aws-cdk-lib//README.md`, then read only the +sections for the constructs you use, for example with +`sed -n ',p' node_modules/aws-cdk-lib//README.md`. Do not +read a whole README into context or re-read a section you have already read. + +## Check your work + +- `%pm-cmd% test` — run the jest unit tests. A build step is not needed for JavaScript. +- `npx cdk synth` — synthesize the CloudFormation template. +- `npx cdk diff` — compare against the deployed stack. +- `npx cdk deploy` changes a real AWS account. Ask the user first. + +## More resources + +- [AWS CDK Reference](https://docs.aws.amazon.com/cdk/api/) diff --git a/packages/aws-cdk/lib/init-templates/app/typescript/AGENTS.template.md b/packages/aws-cdk/lib/init-templates/app/typescript/AGENTS.template.md new file mode 100644 index 000000000..38ad3bf3e --- /dev/null +++ b/packages/aws-cdk/lib/init-templates/app/typescript/AGENTS.template.md @@ -0,0 +1,39 @@ +# AGENTS.md + +This is an AWS CDK app written in TypeScript. The app entry point is the file in +`bin/` that creates the `App`; the stack is defined in `lib/` (the `*-stack.ts` +file). `cdk.json` tells the CDK Toolkit how to run the app. + +## Read the construct library docs before writing code + +AWS CDK service documentation ships inside the aws-cdk-lib package. After you +install dependencies with `npm install` (so `node_modules/aws-cdk-lib` exists) +and before you write your CDK constructs, find the service READMEs once: + +``` +find node_modules/aws-cdk-lib -name README.md +``` + +For each AWS service you use in this app, read that service's module README (for +example, `node_modules/aws-cdk-lib/aws-s3/README.md`) first and follow its +documented construct usage and patterns. Not every service has a README; a +missing one is not an error. Read the relevant READMEs before writing the +constructs for each service. + +Before reading a service README, list its section headings with +`grep -n '^#' node_modules/aws-cdk-lib//README.md`, then read only the +sections for the constructs you use, for example with +`sed -n ',p' node_modules/aws-cdk-lib//README.md`. Do not +read a whole README into context or re-read a section you have already read. + +## Check your work + +- `%pm-cmd% build` — type-check the project. +- `%pm-cmd% test` — run the jest unit tests. +- `npx cdk synth` — synthesize the CloudFormation template. +- `npx cdk diff` — compare against the deployed stack. +- `npx cdk deploy` changes a real AWS account. Ask the user first. + +## More resources + +- [AWS CDK Reference](https://docs.aws.amazon.com/cdk/api/) diff --git a/packages/aws-cdk/lib/init-templates/lib/typescript/.template.npmignore b/packages/aws-cdk/lib/init-templates/lib/typescript/.template.npmignore index c1d6d45dc..111329915 100644 --- a/packages/aws-cdk/lib/init-templates/lib/typescript/.template.npmignore +++ b/packages/aws-cdk/lib/init-templates/lib/typescript/.template.npmignore @@ -1,6 +1,9 @@ *.ts !*.d.ts +# Agent guidance file, not part of the published library +AGENTS.md + # CDK asset staging directory .cdk.staging cdk.out diff --git a/packages/aws-cdk/lib/init-templates/lib/typescript/AGENTS.template.md b/packages/aws-cdk/lib/init-templates/lib/typescript/AGENTS.template.md new file mode 100644 index 000000000..4270f2011 --- /dev/null +++ b/packages/aws-cdk/lib/init-templates/lib/typescript/AGENTS.template.md @@ -0,0 +1,39 @@ +# AGENTS.md + +This is an AWS CDK **construct library** written in TypeScript. The construct is +defined in `lib/` (see `lib/index.ts`); its tests are in `test/`. This library is +meant to be published and consumed by other CDK apps, so it has no `cdk synth` +app of its own. + +## Read the construct library docs before writing code + +AWS CDK service documentation ships inside the aws-cdk-lib package. After you +install dependencies with `npm install` (so `node_modules/aws-cdk-lib` exists) +and before you write your CDK constructs, find the service READMEs once: + +``` +find node_modules/aws-cdk-lib -name README.md +``` + +For each AWS service you use in this library, read that service's module README +(for example, `node_modules/aws-cdk-lib/aws-s3/README.md`) first and follow its +documented construct usage and patterns. Not every service has a README; a +missing one is not an error. Read the relevant READMEs before writing the +constructs for each service. + +Before reading a service README, list its section headings with +`grep -n '^#' node_modules/aws-cdk-lib//README.md`, then read only the +sections for the constructs you use, for example with +`sed -n ',p' node_modules/aws-cdk-lib//README.md`. Do not +read a whole README into context or re-read a section you have already read. + +## Check your work + +- `%pm-cmd% build` — compile TypeScript to JavaScript. +- `%pm-cmd% test` — run the jest unit tests. + +Assert on the synthesized template in tests with `Template.fromStack(...)`. + +## More resources + +- [AWS CDK Reference](https://docs.aws.amazon.com/cdk/api/) diff --git a/packages/aws-cdk/lib/init-templates/sample-app/javascript/AGENTS.template.md b/packages/aws-cdk/lib/init-templates/sample-app/javascript/AGENTS.template.md new file mode 100644 index 000000000..27af43dac --- /dev/null +++ b/packages/aws-cdk/lib/init-templates/sample-app/javascript/AGENTS.template.md @@ -0,0 +1,38 @@ +# AGENTS.md + +This is an AWS CDK app written in JavaScript. The app entry point is the file in +`bin/` that creates the `App`; the stack is defined in `lib/` (the `*-stack.js` +file). `cdk.json` tells the CDK Toolkit how to run the app. + +## Read the construct library docs before writing code + +AWS CDK service documentation ships inside the aws-cdk-lib package. After you +install dependencies with `npm install` (so `node_modules/aws-cdk-lib` exists) +and before you write your CDK constructs, find the service READMEs once: + +``` +find node_modules/aws-cdk-lib -name README.md +``` + +For each AWS service you use in this app, read that service's module README (for +example, `node_modules/aws-cdk-lib/aws-s3/README.md`) first and follow its +documented construct usage and patterns. Not every service has a README; a +missing one is not an error. Read the relevant READMEs before writing the +constructs for each service. + +Before reading a service README, list its section headings with +`grep -n '^#' node_modules/aws-cdk-lib//README.md`, then read only the +sections for the constructs you use, for example with +`sed -n ',p' node_modules/aws-cdk-lib//README.md`. Do not +read a whole README into context or re-read a section you have already read. + +## Check your work + +- `%pm-cmd% test` — run the jest unit tests. A build step is not needed for JavaScript. +- `npx cdk synth` — synthesize the CloudFormation template. +- `npx cdk diff` — compare against the deployed stack. +- `npx cdk deploy` changes a real AWS account. Ask the user first. + +## More resources + +- [AWS CDK Reference](https://docs.aws.amazon.com/cdk/api/) diff --git a/packages/aws-cdk/lib/init-templates/sample-app/typescript/AGENTS.template.md b/packages/aws-cdk/lib/init-templates/sample-app/typescript/AGENTS.template.md new file mode 100644 index 000000000..38ad3bf3e --- /dev/null +++ b/packages/aws-cdk/lib/init-templates/sample-app/typescript/AGENTS.template.md @@ -0,0 +1,39 @@ +# AGENTS.md + +This is an AWS CDK app written in TypeScript. The app entry point is the file in +`bin/` that creates the `App`; the stack is defined in `lib/` (the `*-stack.ts` +file). `cdk.json` tells the CDK Toolkit how to run the app. + +## Read the construct library docs before writing code + +AWS CDK service documentation ships inside the aws-cdk-lib package. After you +install dependencies with `npm install` (so `node_modules/aws-cdk-lib` exists) +and before you write your CDK constructs, find the service READMEs once: + +``` +find node_modules/aws-cdk-lib -name README.md +``` + +For each AWS service you use in this app, read that service's module README (for +example, `node_modules/aws-cdk-lib/aws-s3/README.md`) first and follow its +documented construct usage and patterns. Not every service has a README; a +missing one is not an error. Read the relevant READMEs before writing the +constructs for each service. + +Before reading a service README, list its section headings with +`grep -n '^#' node_modules/aws-cdk-lib//README.md`, then read only the +sections for the constructs you use, for example with +`sed -n ',p' node_modules/aws-cdk-lib//README.md`. Do not +read a whole README into context or re-read a section you have already read. + +## Check your work + +- `%pm-cmd% build` — type-check the project. +- `%pm-cmd% test` — run the jest unit tests. +- `npx cdk synth` — synthesize the CloudFormation template. +- `npx cdk diff` — compare against the deployed stack. +- `npx cdk deploy` changes a real AWS account. Ask the user first. + +## More resources + +- [AWS CDK Reference](https://docs.aws.amazon.com/cdk/api/) diff --git a/packages/aws-cdk/test/commands/init.test.ts b/packages/aws-cdk/test/commands/init.test.ts index 8598f8a1b..8b947905c 100644 --- a/packages/aws-cdk/test/commands/init.test.ts +++ b/packages/aws-cdk/test/commands/init.test.ts @@ -1640,6 +1640,97 @@ test('exercise printing available templates', async () => { await printAvailableTemplates(ioHelper); }); +describe('generated AGENTS.md', () => { + // AGENTS.md ships only for the TypeScript and JavaScript templates, whose + // module READMEs are on disk under node_modules/aws-cdk-lib. + // The third tuple entry is the construct library token the doc must reference. + // The fourth tuple entry is the "check your work" command the doc must mention + // (asserted against the generated, placeholder-substituted file; + // lib/typescript's `%pm-cmd% test` expands to `npm run test`). + // The fifth tuple entry is a snippet from the "Read the construct library docs" + // section, proving the read-docs guidance (list headings, then read sections) is present. + const appCases: Array<[type: string, language: string, docsToken: string, checkCommand: string, readDocsSnippet: string]> = [ + ['app', 'typescript', 'aws-cdk-lib', 'npx cdk synth', "grep -n '^#'"], + ['app', 'javascript', 'aws-cdk-lib', 'npx cdk synth', "grep -n '^#'"], + ['sample-app', 'typescript', 'aws-cdk-lib', 'npx cdk synth', "grep -n '^#'"], + ['sample-app', 'javascript', 'aws-cdk-lib', 'npx cdk synth', "grep -n '^#'"], + ['lib', 'typescript', 'aws-cdk-lib', 'npm run test', "grep -n '^#'"], + ]; + + describe.each(appCases)('%s/%s', (type, language, docsToken, checkCommand, readDocsSnippet) => { + cliTest('generates an AGENTS.md with a docs hint and no leftover placeholders', async (workDir) => { + await cliInit({ + ioHelper, + type, + language, + // Avoid network and dotnet/git side effects; we only assert on generated files. + canUseNetwork: false, + generateOnly: true, + workDir, + }); + + const agentsPath = path.join(workDir, 'AGENTS.md'); + expect(await fs.pathExists(agentsPath)).toBeTruthy(); + + const contents = await fs.readFile(agentsPath, 'utf8'); + // Points agents at the construct library docs and the AWS CDK Reference. + expect(contents).toContain(docsToken); + expect(contents).toContain('https://docs.aws.amazon.com/cdk/api/'); + // The read-docs section tells agents how to find and read service docs. + expect(contents).toContain(readDocsSnippet); + // Guards the language-appropriate verification command against a wrong-command edit. + expect(contents).toContain(checkCommand); + // The `.template.md` variants must have every %placeholder% substituted. + expect(contents).not.toMatch(/%[a-z.-]+%/i); + }); + }); + + // Templates for other languages do not ship an AGENTS.md. csharp/fsharp are + // left out here because their add-project hook shells out to `dotnet`. + const noAgentsCases: Array<[type: string, language: string]> = [ + ['app', 'python'], + ['app', 'java'], + ['app', 'go'], + ['sample-app', 'python'], + ['sample-app', 'java'], + ['sample-app', 'go'], + ]; + + describe.each(noAgentsCases)('%s/%s', (type, language) => { + cliTest('does not generate an AGENTS.md', async (workDir) => { + await cliInit({ + ioHelper, + type, + language, + canUseNetwork: false, + generateOnly: true, + workDir, + }); + + expect(await fs.pathExists(path.join(workDir, 'AGENTS.md'))).toBeFalsy(); + }); + }); + + cliTest('custom --from-path template does not get an AGENTS.md injected', async (workDir) => { + const templateDir = await createSingleLanguageTemplate(workDir, 'my-template', 'typescript'); + const projectDir = path.join(workDir, 'my-project'); + await fs.mkdirp(projectDir); + + await cliInit({ + ioHelper, + fromPath: templateDir, + language: 'typescript', + canUseNetwork: false, + generateOnly: true, + workDir: projectDir, + }); + + // Only files physically present in the custom template are copied; the + // built-in AGENTS.md is not injected into custom templates. + expect(await fs.pathExists(path.join(projectDir, 'AGENTS.md'))).toBeFalsy(); + }); +}); + describe('expandPlaceholders', () => { test('distinguish library and CLI version', () => { const translated = expandPlaceholders('%cdk-version% and %cdk-cli-version%', 'javascript', {