chore: add documentation, coding standards and agent steering files #1118

hjgraca · 2026-01-19T12:59:56Z

Please provide the issue number

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

Added .github/copilot-instructions.md with 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

Introduced .github/instructions/csharp.instructions.md specifying C# naming conventions, type safety, async/await patterns, error handling, thread safety, AWS SDK usage, and documentation requirements for all C# files.
Added .github/instructions/dotnet-architecture-good-practices.instructions.md outlining 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

Created .github/instructions/examples.instructions.md to enforce production-ready standards for example code, including handler patterns, configuration, error handling, testing, documentation, realistic data, and performance best practices for files in examples/**/*.cs.

User experience

Please share what the user experience looks like before and after this change

Checklist

Please leave checklist items unchecked if they do not apply to your change.

Meets tenets criteria
I have performed a self-review of this change
Changes have been tested
Changes are documented
PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

Migration process documented
Implement warnings (if it can live side by side)

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.

…build commands, project structure, and coding standards

…evelopment

…ebugging test failures, and running E2E tests

Copilot

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.

Copilot · 2026-01-19T13:03:21Z

.kiro/steering/Powertools.md

@@ -0,0 +1,79 @@
+---


Inconsistent capitalization in the comment. "Github" should be "GitHub" (with capital H) for consistency with the standard brand name.

Copilot · 2026-01-19T13:03:22Z

.github/skills/run-e2e-tests/SKILL.md

+# Get recent log events
+aws logs filter-log-events \
+    --log-group-name "/aws/lambda/PowertoolsLoggingTest" \
+    --start-time $(date -v-1H +%s000)


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.

Suggested change

--start-time $(date -v-1H +%s000)

--start-time "$(date -v-1H +%s000 2>/dev/null || date -d '1 hour ago' +%s000)"

Copilot · 2026-01-19T13:03:22Z

.github/skills/create-aspect-attribute/SKILL.md

+    /// <summary>
+    /// Called after method execution (success or failure).
+    /// </summary>
+    public void OnExit(AspectEventArgs eventArgs)
+    {
+        // Cleanup resources, flush buffers, close connections, etc.
+    }


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.

Copilot · 2026-01-19T13:03:22Z

.github/instructions/tests.instructions.md

+
+```csharp
+[Fact]
+public void LogInformation_Should_WriteStructuredJson_When_ValidMessageProvided()


The test naming convention example uses "When_ValidMessageProvided" which is grammatically awkward. Consider using "When_ValidMessageIsProvided" or "When_ValidMessageGiven" for better readability and clarity.

Copilot · 2026-01-19T13:03:23Z

.github/instructions/csharp.instructions.md

+public async Task<string> GetParameterAsync(string name, CancellationToken cancellationToken = default)
+{
+    var response = await _client.GetParameterAsync(request, cancellationToken).ConfigureAwait(false);


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.

Suggested change

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);

Copilot · 2026-01-19T13:03:23Z

.github/skills/create-aspect-attribute/SKILL.md

+/// {
+///     // Handler implementation
+/// }
+/// </code>


Inconsistent spacing in XML documentation example. The closing tag should have proper indentation and spacing for better readability in documentation examples.

Suggested change

/// </code>

/// </code>

Copilot · 2026-01-19T13:03:23Z

.github/skills/add-new-utility/SKILL.md

+```bash
+dotnet add package AWS.Lambda.Powertools.{UtilityName}
+```


Missing closing backtick for the code block. The markdown code fence should be properly closed with three backticks to ensure proper rendering.

Copilot · 2026-01-19T13:03:23Z

.github/instructions/dotnet-architecture-good-practices.instructions.md

+public void Configure(string serviceName)
+{
+    ArgumentNullException.ThrowIfNull(serviceName);
+    ArgumentException.ThrowIfNullOrWhiteSpace(serviceName);


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.

Suggested change

ArgumentException.ThrowIfNullOrWhiteSpace(serviceName);

if (string.IsNullOrWhiteSpace(serviceName))

{

throw new ArgumentException("Service name cannot be empty or whitespace.", nameof(serviceName));

}

sonarqubecloud · 2026-01-22T10:39:33Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

hjgraca added 4 commits January 9, 2026 13:09

chore: update documentation and guidelines for Powertools, including …

2764626

…build commands, project structure, and coding standards

chore: add SOLID principles and architecture guidelines for library d…

ec02375

…evelopment

chore: add skills for AOT compatibility, aspect attribute creation, d…

d2e2d88

…ebugging test failures, and running E2E tests

chore: add guide for creating new Powertools utility packages

d89c08c

Copilot AI review requested due to automatic review settings January 19, 2026 12:59

boring-cyborg bot added the internal Maintenance changes label Jan 19, 2026

pull-request-size bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Jan 19, 2026

Merge branch 'develop' into chore/add-agent-files

7c7236a

Copilot started reviewing on behalf of hjgraca January 19, 2026 13:00 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

fix naming

012c60e

hjgraca linked an issue Jan 19, 2026 that may be closed by this pull request

Maintenance: introduce documentation, steering files and coding standards for Agents #1117

Open

1 task

hjgraca closed this Jan 22, 2026

hjgraca reopened this Jan 22, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: add documentation, coding standards and agent steering files #1118

chore: add documentation, coding standards and agent steering files #1118

Uh oh!

hjgraca commented Jan 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

sonarqubecloud bot commented Jan 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	--start-time $(date -v-1H +%s000)
	--start-time "$(date -v-1H +%s000 2>/dev/null \|\| date -d '1 hour ago' +%s000)"

-    ArgumentException.ThrowIfNullOrWhiteSpace(serviceName);
+    if (string.IsNullOrWhiteSpace(serviceName))
+    {
+        throw new ArgumentException("Service name cannot be empty or whitespace.", nameof(serviceName));
+    }

chore: add documentation, coding standards and agent steering files #1118

Are you sure you want to change the base?

chore: add documentation, coding standards and agent steering files #1118

Uh oh!

Conversation

hjgraca commented Jan 19, 2026

Summary

Changes

User experience

Checklist

Acknowledgment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Jan 22, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant