Skip to content

Maintenance: write down the project premises so people and agents can follow them #8716

Closed

Description

@leandrodamascena

Why is this needed?

This month we got more contributions than ever, and a good share of them were written with AI assistance. Most were valid. What they got wrong was never the code itself, it was project knowledge that lives in my head and in old PR threads: the layer must not ship boto3, get() and get_parameters_by_name share a cache key, we warn before we raise, tests only go through the public API, a probe runs once per process. I ended up re-explaining the same things in review, one PR at a time.

Our tenets describe what goes into the product. Nothing describes how we build it. If it is not written in the repo, nobody can find it, human or model.

Which area does this relate to?

Other

Solution

One PR with:

  • AGENTS.md at the root, short and pointer-style: how to run tests and lint, PR rules the CI enforces, and the things we do not do. CLAUDE.md is one line pointing to it.
  • docs/adr/ with short ADRs (one page, MADR) for the premises I keep repeating: Lambda-first, every millisecond counts, Python versions we support, layer and packaging, tests are a contract, zero regression and compatibility, lean dependencies. More later, one per decision we have to explain twice.
  • A disclaimer in the README.md: AI-assisted issues and PRs are welcome, as long as you say so and tell us how you verified the change, tests you ran yourself and the real service when it applies. Same sentence in CONTRIBUTING.md, plus a field in the PR and bug report templates to make the declaration part of the flow.

Nothing here changes the code or the public API.

Acknowledgment

Activity

  1. added this to the 3.40.0 milestone on Oct 30, 2026
  2. added
    documentationImprovements or additions to documentation
    triagePending triage from maintainers
    internalMaintenance changes
    on Oct 30, 2026
  3. powertools-for-aws-oss-automation commented on Oct 30, 2026

    @powertools-for-aws-oss-automation

    Warning

    This issue is now closed. Please be mindful that future comments are hard for our team to see.
    If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
    If you wish to keep having a conversation with other community members under this issue feel free to do so.

  4. github-actions commented on Nov 3, 2026

    @github-actions
    Contributor

    This is now released under 3.39.0 version!

  5. removed
    pending-releaseFix or implementation already in dev waiting to be released
    on Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

documentationImprovements or additions to documentationinternalMaintenance changes

Type

No type

Projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions