agentleFS
membranemembrane/api-gateway/CLAUDE.md

api-gateway

CLAUDE.md658 starsChanged 3 months agoApache-2.0View on GitHub

Membrane API Gateway — a lightweight Java API gateway for REST, GraphQL, and legacy SOAP/WSDL services, configurable in YAML or XML. Upstream: https://github.com/membrane/api-gateway - NEVER commit, push, or open/merge a PR unless the user explicitly asks for it in that moment. Stage nothing automatically; report what changed and wait. - Use Closes #<issue> in commit messages when the work resolves a filed issue. - Never mention Claude in commit messages, pull requests, or issues — no Co-Authored-By: Claude trailer, no…

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

22 rules. About 0 are common, 4 are distinctive, and 18 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 18

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    NEVER commit, push, or open/merge a PR unless the user explicitly asks for it in that moment.

    line 8
  2. Very specific:

    Use Closes #<issue> in commit messages when the work resolves a filed issue.

    line 10
  3. Very specific:

    Never mention Claude in commit messages, pull requests, or issues — no Co-Authored-By: Claude trailer, no "Generated with Claude Code" …

    line 11
  4. Very specific:

    Never commit customer-derived artifacts — real customer names, WSDLs, XML, or sample payloads, not even as test fixtures.

    line 13
  5. Very specific:

    Don't refactor, reformat, or "improve" adjacent code, even if it's messy.

    line 19
  6. Distinctive:

    If a simpler approach than the one requested exists, say so, even if it means pushing back.

    line 23
  7. Very specific:

    Every new function or feature needs at least one test.

    line 59
  8. Very specific:

    Test classes mirror the package of the class under test (…core.util.URLUtil → …core.util.URLUtilTest) and are package-private, as are @Test …

    line 62
  9. Very specific:

    Before running Membrane tests, check that ports 2000/2001/3000/7007/9000 are free (lsof -nP -iTCP:2000,2001,3000,7007,9000 -sTCP:LISTEN).

    line 64
  10. Distinctive:

    Every annotated setter needs a matching getter.

    line 75
  11. Very specific:

    Only these block tags are read: @topic, @description, @example, @default, @explanation (deprecated, use @description), @deprecated, @yaml.

    line 90
  12. Very specific:

    Use HTML markup (<pre><code>...</code></pre> for code, not {@code}), no named HTML entities, don't open with an empty tag like <p/>.

    line 99
  13. Very specific:

    Use the optimize-interceptor-docs skill when writing/polishing these docs, find-interceptor-impl to go from an XML tag name to its Java …

    line 102
  14. Very specific:

    Don't abbreviate parameter names in public interfaces (private methods: fine) — docs/CONVENTIONS.md.

    line 112
  15. Very specific:

    Prefer SequencedCollection.getFirst() over .get(0).

    line 113
  16. Very specific:

    Prefer final fields, parameters, and locals, and immutable data over mutating caller-owned collections: List.of or List.copyOf for an …

    line 115
  17. Very specific:

    Use var for local variables in new or changed code instead of repeating the concrete type (final var list = new ArrayList<String>(), final …

    line 119
  18. Very specific:

    Prefer String.formatted() (or String.format) over + concatenation once a string mixes several values with literal text ("%s %s failed with …

    line 125
  19. Very specific:

    Keep + for simple joins of two or three parts (host + ":" + port).

    line 127
  20. Very specific:

    Before writing a new helper, or when refactoring, check docs/UTILITIES.md — a catalog of the core util classes (text/string, HTTP/URI, …

    line 139
  21. Distinctive:

    Read it when a task touches such code.

    line 141
  22. Very specific:

    When drafting release notes (release-notes skill), exclude internal refactors with no user-visible effect and routine recurring maintenance …

    line 147

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

Membrane API Gateway — a lightweight Java API gateway for REST, GraphQL, and legacy SOAP/WSDL services, configurable in YAML or XML. Upstream: https://github.com/membrane/api-gateway

Git & Commit Policy

  • NEVER commit, push, or open/merge a PR unless the user explicitly asks for it in that moment. Stage nothing automatically; report what changed and wait.
  • Use Closes #<issue> in commit messages when the work resolves a filed issue.
  • Never mention Claude in commit messages, pull requests, or issues — no Co-Authored-By: Claude trailer, no "Generated with Claude Code" footer, no reference in titles or bodies.
  • Never commit customer-derived artifacts — real customer names, WSDLs, XML, or sample payloads, not even as test fixtures. Generate synthetic equivalents (example.com-style) or reuse existing generic fixtures.

Working principles

  • Don't refactor, reformat, or "improve" adjacent code, even if it's messy. Remove imports/vars/methods your change made unused; leave pre-existing dead code alone (mention it, don't touch it).
  • For bug fixes: reproduce with a failing test first, then fix.
  • If a simpler approach than the one requested exists, say so, even if it means pushing back.

Modules

Maven multi-module reactor (root pom.xml), Java 21 (javac.source/target):

  • annot — the @MCElement/@MCAttribute/... annotations that drive the config grammar; also generates router-conf.xsd.
  • core — the router engine and all built-in interceptors/plugins. Primary library code.
  • distribution — assembles the runnable .zip (membrane.sh/membrane.cmd, conf/proxies.xml, tutorials/, examples/). Also owns the tutorial/example integration tests. distribution/router/conf/ is what actually ships as the zip's conf/ (see src/assembly/distribution.xml); distribution/conf/ is a separate, unpackaged scratch directory for the programmer's own local testing — never treat it as shipped config or reference it from tutorials/examples/docs.
  • war — packages core for deployment into a servlet container (Tomcat, Jetty).
  • test — shared test utilities (HTTP client helpers, fixtures), depended on as test scope.

Build

mvn install -DskipTests          # full build, skip tests
mvn -pl core -am -DskipTests package   # one module + its dependencies

Testing

  • To run tests, use the test-runner agent — it owns this repo's run mechanics: the -Dtest/-Dit.test suite traps that silently run the wrong scope, run-core-test.sh for a single core class, rebuilding the distribution zip before tutorial/example ITs, macOS locale flags, and the fixed-port (2000/3000/7007) conflicts that fake a regression. Don't hand-roll the Maven invocation.
  • Run only the tests affected by a change — the class(es)/package(s) touched, and report pass counts. Never run a full unit test run (mvn test / mvn -pl core -am test) or the full distribution IT suite without asking first; these are slow and often fail on unrelated/network-dependent tests offline.
  • Every new function or feature needs at least one test. Before writing a new test class, check <module>/src/test/java/<mirrored package>/ for an existing test class covering that production class and add a method there; only create <ClassName>Test if none exists.
  • Test classes mirror the package of the class under test (…core.util.URLUtil → …core.util.URLUtilTest) and are package-private, as are @Test methods.
  • Before running Membrane tests, check that ports 2000/2001/3000/7007/9000 are free (lsof -nP -iTCP:2000,2001,3000,7007,9000 -sTCP:LISTEN); an IDE-launched Membrane instance frequently blocks test runs.
  • Integration tests can be flaky for environmental reasons (TIME_WAIT collisions on macOS, accept backlog limits). Triage a failure as environmental before changing product code.

Configuration grammar (annotations)

Config elements are Java classes annotated in the annot module and rendered into both XML and YAML. See docs/DEVELOPING.md for the full annotation reference (@MCElement, @MCAttribute, @MCChildElement, @MCTextContent, @MCOtherAttributes, @Required). Every annotated setter needs a matching getter.

YAML $schema= version comments

The # yaml-language-server: $schema=https://www.membrane-api.io/vX.Y.Z.json header comment on any .yaml/.yml file in the repo (not just distribution/tutorials/ — the release tooling walks the whole project tree) is rewritten automatically as part of cutting a release (ConsistentVersionNumbers.java, run from the release-pr.yml GitHub Action). Don't hand-edit it, and don't flag a stale/mismatched version as a bug in review.

Reference docs (Javadoc → membrane-api.io)

Class/method Javadoc on @MCElement classes is parsed by a custom doc generator, not standard Javadoc rendering:

  • Only these block tags are read: @topic, @description, @example, @default, @explanation (deprecated, use @description), @deprecated, @yaml. Plain prose before the first tag is silently dropped — everything must live inside a tag.
  • @topic belongs only on top-level flow/API elements (component=true, usable at the top level) — not on nested/child-only config elements.
  • Class-level @description must not describe individual attributes (that belongs in each setter's own @description); it may name technologies/values in prose.
  • Doc examples must cite tutorials (distribution/tutorials/...) only — never distribution/examples (being phased out). Omit the link entirely if no tutorial exists yet.
  • Use HTML markup (<pre><code>...</code></pre> for code, not {@code}), no named HTML entities, don't open with an empty tag like <p/>.

Use the optimize-interceptor-docs skill when writing/polishing these docs, find-interceptor-impl to go from an XML tag name to its Java class, and find-example/create-tutorial for example/tutorial discovery and scaffolding.

Code style

  • Interceptors must be thread safe (Interceptor javadoc): one instance per config element serves every request thread, and <call>/internal routing can re-enter it on its own thread. Keep per-request state in locals or on the Exchange; fields hold configuration, written before init() and read-only afterwards.
  • Don't abbreviate parameter names in public interfaces (private methods: fine) — docs/CONVENTIONS.md.
  • Prefer SequencedCollection.getFirst() over .get(0); custom list-like wrappers (e.g. ValidationErrors) should expose a delegating getFirst().
  • Prefer final fields, parameters, and locals, and immutable data over mutating caller-owned collections: List.of or List.copyOf for an immutable snapshot; Collections.unmodifiableList only as a read-only view — it still reflects later changes to the backing list, so use it when that live behaviour is intended, not as a defensive copy.
  • Use var for local variables in new or changed code instead of repeating the concrete type (final var list = new ArrayList<String>(), final var exc = get("/foo").buildExchange(); the final comes from the rule above, var only replaces the type). Keep explicit types for fields, parameters and return types, which var can't replace anyway, and where the initializer doesn't show the type (e.g. null, or a lambda that needs a target type). Don't convert untouched existing code.
  • Prefer String.formatted() (or String.format) over + concatenation once a string mixes several values with literal text ("%s %s failed with status %d".formatted(method, uri, status)). Keep + for simple joins of two or three parts (host + ":" + port). In SLF4J calls use {} placeholders, not either of these.
  • SLF4J everywhere; no System.out in production code.
  • Attack/validation-detection log lines (e.g. XXE/DOCTYPE detection) are intentionally info, not warn — that's an ops-tunable level, not a severity bug to flag in review.
  • Log levels and sensitive data: debug/trace may log anything (raw headers, cookies, bodies, unescaped input), because they are not for production; don't flag that in review. info, warn and error must not expose secrets (credentials, tokens, session IDs, private keys) and must escape untrusted values with TextUtil.escapeControlCharsForLog.

Utility classes

Before writing a new helper, or when refactoring, check docs/UTILITIES.md — a catalog of the core util classes (text/string, HTTP/URI, SOAP/JSON, collections, files/network, OpenAPI, test helpers) with a one-line purpose each. Read it when a task touches such code; reuse or extend these classes instead of adding private duplicates. Open individual classes by name or grep by behavior rather than browsing the packages. When you add, rename or remove a util class, update that file.

Release notes

When drafting release notes (release-notes skill), exclude internal refactors with no user-visible effect and routine recurring maintenance (doc/javadoc polishing) — readers care about behavior, config, and capability changes only.

docs/SECURITY.md

The supported-versions table intentionally lists only the current minor line even though older lines (e.g. 6.5.x) still receive maintenance releases sometimes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.