aws / aws/aws-cdk

docs: provide structured guidance for LLMs to improve CDK recommendations

Open
#35,935 2 comments 2 reactions 0 assignees View on GitHub
aws-cdk-lib docs/guide effort/medium feature-request p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
2d 3h
Merged PRs (30d)
83

Description

### Describe the feature

Add an `llms.txt` file to the CDK documentation following the standard at https://llmstxt.org/ to provide structured information that helps LLMs give better CDK guidance and recommendations.

### Use Case

When LLMs assist developers with CDK code, they often lack structured guidance on CDK best practices, leading to suboptimal recommendations. Sometimes LLMs suggest L1 instead of L2 constructs, or provide outdated patterns. A standardized `llms.txt` file would help LLMs understand CDK conventions and best practices, similar to how AWS Powertools implemented this at https://docs.aws.amazon.com/powertools/python/latest/llms-full.txt

### Proposed Solution

Create an `llms.txt` file at [CDK Construct Library API Reference Doc](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) that includes:

- Emphasis on using L2 constructs over L1 constructs as best practice
- CDK construct patterns and naming conventions
- Common anti-patterns to avoid
- Security best practices
...

In future we can embed similar LLM guidance to other CDK sites such as [CDK Developer Guide](https://docs.aws.amazon.com/cdk/v2/guide/home.html), [Construct Hub](https://constructs.dev/) etc.

Reference the https://llmstxt.org/ specification for formatting standards.

### Other Information

_No response_

### Acknowledgements

- [ ] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

### AWS CDK Library version (aws-cdk-lib)

n/a

### AWS CDK CLI version

n/a

### Environment details (OS name and version, etc.)

n/a

Contributor guide

Open the contributing guide

Research direction

Start with the llmstxt.org specification and the CDK Construct Library API Reference linked in the issue. Create the requested llms.txt with guidance on L2 versus L1 constructs, naming conventions, anti-patterns, and security practices. Done means the file follows the standard and covers the listed CDK guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.