Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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/<module>/README.md`, then read only the
sections for the constructs you use, for example with
`sed -n '<start>,<end>p' node_modules/aws-cdk-lib/<module>/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/)
Original file line number Diff line number Diff line change
@@ -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/<module>/README.md`, then read only the
sections for the constructs you use, for example with
`sed -n '<start>,<end>p' node_modules/aws-cdk-lib/<module>/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/)
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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/<module>/README.md`, then read only the
sections for the constructs you use, for example with
`sed -n '<start>,<end>p' node_modules/aws-cdk-lib/<module>/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/)
Original file line number Diff line number Diff line change
@@ -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/<module>/README.md`, then read only the
sections for the constructs you use, for example with
`sed -n '<start>,<end>p' node_modules/aws-cdk-lib/<module>/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/)
Original file line number Diff line number Diff line change
@@ -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/<module>/README.md`, then read only the
sections for the constructs you use, for example with
`sed -n '<start>,<end>p' node_modules/aws-cdk-lib/<module>/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/)
91 changes: 91 additions & 0 deletions packages/aws-cdk/test/commands/init.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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', {
Expand Down
Loading