docs: provide structured guidance for LLMs to improve CDK recommendations
- 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
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