Skip to content

docs: add agent design rules and review checks (AGENTS.md, REVIEW.md) - #136

Draft
joe4dev wants to merge 13 commits into
mainfrom
devx-1089-update-the-app-inspector-mcp-tool-with-iam
Draft

joe4dev wants to merge 13 commits into
mainfrom
devx-1089-update-the-app-inspector-mcp-tool-with-iam

Conversation

@joe4dev

@joe4dev joe4dev commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Motivation

Agents and reviewers working on this server had no written design rules. Several patterns in the code also go against where the project is heading: the legacy localstack CLI, awslocal-style wrappers, parsing logs, private LocalStack internals, and computing in the client what LocalStack should decide. This PR writes the rules down so new code follows them, and lists where existing code doesn't yet.

Solution

  • AGENTS.md (with CLAUDE.md pointing to it): commands, layout, how to write a tool, and the design rules.
    • Work with lstk and never the legacy CLI, and use lstk's cloud and IaC commands, with no wrapper fallback.
    • Prefer LocalStack APIs over logs, and use only public interfaces. Ask before adopting a new API.
    • Compute in LocalStack and render in the server; client-side exceptions only with explicit approval.
    • Testing rules for MCP tools, dependency pinning through Dependabot, and Docker image size (ask before more than about 50 MB or a new runtime).
    • The design for IAM in localstack-app-inspector (not implemented here).
    • Gaps in LocalStack, known deviations, open questions and follow-ups.
  • REVIEW.md: the rules as review checks with severities. §0 makes leaking secrets through CI a BLOCKER, with checks for external-collaborator and Dependabot PRs.
  • Known deviations cover existing code on main only. New code follows the rules. A change that needs to break one raises it first, and a change that touches a listed deviation says what it did about it.
  • "Maintaining this file": no counts, versions or growing lists in AGENTS.md. Lists the code can check belong in ratchet tests (a follow-up PR), and deviations are described by pattern.
  • Docs only: no code changes. The IAM actions and the agentic eval are planned work and will come in their own PRs.

Adversarial review

Ten rounds of adversarial review checked both files against this branch's code, lstk, the LocalStack specs and the public docs. The last round found no blockers. Decisions still open, recorded in the files:

  • How the server passes its target to lstk ("Open questions").
  • The IAM design's two new APIs need a maintainer's approval in the PR that adds them.
  • /_localstack/licenseinfo is listed as a known deviation until LocalStack documents a way to check licensed features.

Review

Advise review: these files set rules for every future change, and they contain decisions (endpoint scoping, container names, the IAM design) that the team should agree on.

🤖 Generated with Claude Code

joe4dev and others added 13 commits November 19, 2026 16:54
AGENTS.md records the design rules for the MCP servers (compute in
LocalStack, public interfaces only) and the approved client-side
exceptions, starting with grouping App Inspector failed requests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… with main

Adds REVIEW.md §0 (secret leaks through CI, external and Dependabot PRs),
dependency pinning for Dependabot, Docker image size, and testing rules for
MCP tools. Known deviations now cover existing code on main only; the IAM
actions are documented as design and the agentic eval as a follow-up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replace counts, versions, port ranges and field lists with rules and pointers to
the source, and add "Maintaining this file": lists the code can check belong in
ratchet tests, deviations are described by pattern.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…fo, endpoint proposal)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… payload fields, deviations intro)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…eptions home)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…endency sources)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ions by pattern)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…analytics allowlist)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed pins)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…mage size on bumps)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…udit scope)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… to the change, testable escaping)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant