chore: add documentation, coding standards and agent steering files#1118
chore: add documentation, coding standards and agent steering files#1118
Conversation
…build commands, project structure, and coding standards
…ebugging test failures, and running E2E tests
pull-request-size
bot
added
the
size/XXL
There was a problem hiding this comment.
Pull request overview
This PR introduces comprehensive documentation and coding standards for the Powertools for AWS Lambda (.NET) project, including AI agent steering files, skill guides, and coding standards. The documentation aims to ensure code quality, maintainability, and production readiness across all libraries and examples.
Changes:
- Added root-level AGENTS.md with project overview, build commands, code style guidelines, and architecture patterns
- Created Kiro AI steering files covering technology stack, project structure, product description, and critical development rules
- Added GitHub Skills documentation for common development tasks (E2E testing, debugging, creating AOP attributes, AOT compatibility, adding utilities)
- Introduced coding standards and best practices for C#, .NET architecture, tests, and examples
- Modified .gitignore to track previously excluded AI agent configuration directories
Reviewed changes
Copilot reviewed 15 out of 16 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| AGENTS.md | Comprehensive guide for AI coding agents covering project structure, build commands, conventions, and patterns |
| .kiro/steering/tech.md | Technology stack documentation including runtime, dependencies, and build commands |
| .kiro/steering/structure.md | Project structure, naming conventions, and file organization |
| .kiro/steering/product.md | Product overview describing core utilities and target audience |
| .kiro/steering/Powertools.md | Critical rules and quick reference for AI agents |
| .gitignore | Removes exclusions for AI configuration directories to allow tracking |
| .github/skills/run-e2e-tests/SKILL.md | Guide for deploying infrastructure and running E2E tests |
| .github/skills/debug-test-failures/SKILL.md | Troubleshooting guide for common test failure patterns |
| .github/skills/create-aspect-attribute/SKILL.md | Step-by-step guide for creating new AOP aspect attributes |
| .github/skills/aot-compatibility/SKILL.md | Guide for ensuring Native AOT compatibility |
| .github/skills/add-new-utility/SKILL.md | Comprehensive guide for scaffolding new utility packages |
| .github/instructions/tests.instructions.md | Test code standards and patterns |
| .github/instructions/examples.instructions.md | Example code standards for production-ready patterns |
| .github/instructions/dotnet-architecture-good-practices.instructions.md | SOLID principles, clean architecture, and design patterns guidance |
| .github/instructions/csharp.instructions.md | C# coding standards for naming, async/await, error handling, and documentation |
| .github/copilot-instructions.md | GitHub Copilot-specific instructions covering AOP architecture and conventions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,79 @@ | |||
| --- | |||
There was a problem hiding this comment.
Inconsistent capitalization in the comment. "Github" should be "GitHub" (with capital H) for consistency with the standard brand name.
| # Get recent log events | ||
| aws logs filter-log-events \ | ||
| --log-group-name "/aws/lambda/PowertoolsLoggingTest" \ | ||
| --start-time $(date -v-1H +%s000) |
There was a problem hiding this comment.
The date command with '-v' flag is macOS-specific syntax. On Linux systems, this should be 'date -d "1 hour ago" +%s000'. Consider providing both versions or using a more portable command for better cross-platform compatibility in documentation.
| --start-time $(date -v-1H +%s000) | |
| --start-time "$(date -v-1H +%s000 2>/dev/null || date -d '1 hour ago' +%s000)" |
| /// <summary> | ||
| /// Called after method execution (success or failure). | ||
| /// </summary> | ||
| public void OnExit(AspectEventArgs eventArgs) | ||
| { | ||
| // Cleanup resources, flush buffers, close connections, etc. | ||
| } |
There was a problem hiding this comment.
The comment states "Called after method execution (success or failure)" but this is misleading. The OnExit method is called in the finally block, so it runs regardless of success or failure. However, it's important to note that if OnEntry throws an exception, OnExit will not be called. Consider clarifying this behavior in the documentation.
|
|
||
| ```csharp | ||
| [Fact] | ||
| public void LogInformation_Should_WriteStructuredJson_When_ValidMessageProvided() |
There was a problem hiding this comment.
The test naming convention example uses "When_ValidMessageProvided" which is grammatically awkward. Consider using "When_ValidMessageIsProvided" or "When_ValidMessageGiven" for better readability and clarity.
| public async Task<string> GetParameterAsync(string name, CancellationToken cancellationToken = default) | ||
| { | ||
| var response = await _client.GetParameterAsync(request, cancellationToken).ConfigureAwait(false); |
There was a problem hiding this comment.
Inconsistency in code example. The comment says "Library code pattern" but uses 'response' in the return statement without showing where it comes from. Consider showing the complete example including the response variable assignment for clarity.
| public async Task<string> GetParameterAsync(string name, CancellationToken cancellationToken = default) | |
| { | |
| var response = await _client.GetParameterAsync(request, cancellationToken).ConfigureAwait(false); | |
| private readonly IAmazonSimpleSystemsManagement _client; | |
| public async Task<string> GetParameterAsync(string name, CancellationToken cancellationToken = default) | |
| { | |
| var request = new GetParameterRequest | |
| { | |
| Name = name | |
| }; | |
| var response = await _client.GetParameterAsync(request, cancellationToken) | |
| .ConfigureAwait(false); |
| /// { | ||
| /// // Handler implementation | ||
| /// } | ||
| /// </code> |
There was a problem hiding this comment.
Inconsistent spacing in XML documentation example. The closing tag should have proper indentation and spacing for better readability in documentation examples.
| /// </code> | |
| /// </code> |
| ```bash | ||
| dotnet add package AWS.Lambda.Powertools.{UtilityName} | ||
| ``` |
There was a problem hiding this comment.
Missing closing backtick for the code block. The markdown code fence should be properly closed with three backticks to ensure proper rendering.
| public void Configure(string serviceName) | ||
| { | ||
| ArgumentNullException.ThrowIfNull(serviceName); | ||
| ArgumentException.ThrowIfNullOrWhiteSpace(serviceName); |
There was a problem hiding this comment.
The example uses 'ArgumentException.ThrowIfNullOrWhiteSpace' which is a .NET 8+ method. While this is appropriate given the target framework, it should be noted that this method doesn't exist in earlier .NET versions for developers referencing this documentation.
| ArgumentException.ThrowIfNullOrWhiteSpace(serviceName); | |
| if (string.IsNullOrWhiteSpace(serviceName)) | |
| { | |
| throw new ArgumentException("Service name cannot be empty or whitespace.", nameof(serviceName)); | |
| } |
|
1 participant
Issue number: #1117
Summary
Changes
This pull request introduces documentation and coding standards for the Powertools for AWS Lambda (.NET) project. It adds a detailed architecture overview, developer instructions, and file-specific guidelines to ensure code quality, maintainability, and production readiness across all libraries and examples.
Project Architecture and Usage Documentation
.github/copilot-instructions.mdwith an overview of the Powertools architecture, AOP implementation details, build/test commands, conventions for AOT compatibility, thread safety, async patterns, file organization, testing, security, and references to key files.C# and .NET Coding Standards
.github/instructions/csharp.instructions.mdspecifying C# naming conventions, type safety, async/await patterns, error handling, thread safety, AWS SDK usage, and documentation requirements for all C# files..github/instructions/dotnet-architecture-good-practices.instructions.mdoutlining SOLID principles, clean architecture layering, design patterns (AOP, singleton, builder), modern C# features, AOT compatibility, implementation checklist, and anti-patterns to avoid for C# and project files.Example Code Guidelines
.github/instructions/examples.instructions.mdto enforce production-ready standards for example code, including handler patterns, configuration, error handling, testing, documentation, realistic data, and performance best practices for files inexamples/**/*.cs.User experience
Checklist
Please leave checklist items unchecked if they do not apply to your change.
Is this a breaking change?
RFC issue number:
Checklist:
Acknowledgment
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.
Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.