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…
In this repository10 other files it gives its agents.
- config-error-handlingSkill
- create-tutorialSkill
- find-exampleSkill
- find-interceptor-implSkill
- membrane-configSkill
- optimize-interceptor-docsSkill
- refactorSkill
- release-notesSkill
- review-branchSkill
- run-example-testSkill
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
- Distinctive: line 8
NEVER commit, push, or open/merge a PR unless the user explicitly asks for it in that moment.
- Very specific: line 10
Use Closes #<issue> in commit messages when the work resolves a filed issue.
- Very specific: line 11
Never mention Claude in commit messages, pull requests, or issues — no Co-Authored-By: Claude trailer, no "Generated with Claude Code" …
- Very specific: line 13
Never commit customer-derived artifacts — real customer names, WSDLs, XML, or sample payloads, not even as test fixtures.
- Very specific: line 19
Don't refactor, reformat, or "improve" adjacent code, even if it's messy.
- Distinctive: line 23
If a simpler approach than the one requested exists, say so, even if it means pushing back.
- Very specific: line 59
Every new function or feature needs at least one test.
- Very specific: line 62
Test classes mirror the package of the class under test (…core.util.URLUtil → …core.util.URLUtilTest) and are package-private, as are @Test …
- Very specific: line 64
Before running Membrane tests, check that ports 2000/2001/3000/7007/9000 are free (lsof -nP -iTCP:2000,2001,3000,7007,9000 -sTCP:LISTEN).
- Distinctive: line 75
Every annotated setter needs a matching getter.
- Very specific: line 90
Only these block tags are read: @topic, @description, @example, @default, @explanation (deprecated, use @description), @deprecated, @yaml.
- Very specific: line 99
Use HTML markup (<pre><code>...</code></pre> for code, not {@code}), no named HTML entities, don't open with an empty tag like <p/>.
- Very specific: line 102
Use the optimize-interceptor-docs skill when writing/polishing these docs, find-interceptor-impl to go from an XML tag name to its Java …
- Very specific: line 112
Don't abbreviate parameter names in public interfaces (private methods: fine) — docs/CONVENTIONS.md.
- Very specific: line 113
Prefer SequencedCollection.getFirst() over .get(0).
- Very specific: line 115
Prefer final fields, parameters, and locals, and immutable data over mutating caller-owned collections: List.of or List.copyOf for an …
- Very specific: line 119
Use var for local variables in new or changed code instead of repeating the concrete type (final var list = new ArrayList<String>(), final …
- Very specific: line 125
Prefer String.formatted() (or String.format) over + concatenation once a string mixes several values with literal text ("%s %s failed with …
- Very specific: line 127
Keep + for simple joins of two or three parts (host + ":" + port).
- Very specific: line 139
Before writing a new helper, or when refactoring, check docs/UTILITIES.md — a catalog of the core util classes (text/string, HTTP/URI, …
- Distinctive: line 141
Read it when a task touches such code.
- Very specific: line 147
When drafting release notes (release-notes skill), exclude internal refactors with no user-visible effect and routine recurring maintenance …
≈ “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.
Files
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: Claudetrailer, 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 generatesrouter-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'sconf/(seesrc/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— packagescorefor deployment into a servlet container (Tomcat, Jetty).test— shared test utilities (HTTP client helpers, fixtures), depended on astestscope.
Build
mvn install -DskipTests # full build, skip tests
mvn -pl core -am -DskipTests package # one module + its dependenciesTesting
- To run tests, use the
test-runneragent — it owns this repo's run mechanics: the-Dtest/-Dit.testsuite traps that silently run the wrong scope,run-core-test.shfor a singlecoreclass, 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>Testif none exists. - Test classes mirror the package of the class under test (
…core.util.URLUtil→…core.util.URLUtilTest) and are package-private, as are@Testmethods. - 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. @topicbelongs only on top-level flow/API elements (component=true, usable at the top level) — not on nested/child-only config elements.- Class-level
@descriptionmust 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 — neverdistribution/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 (
Interceptorjavadoc): 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 theExchange; fields hold configuration, written beforeinit()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 delegatinggetFirst(). - Prefer
finalfields, parameters, and locals, and immutable data over mutating caller-owned collections:List.oforList.copyOffor an immutable snapshot;Collections.unmodifiableListonly 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
varfor 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(); thefinalcomes from the rule above,varonly replaces the type). Keep explicit types for fields, parameters and return types, whichvarcan'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()(orString.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.outin production code. - Attack/validation-detection log lines (e.g. XXE/DOCTYPE detection) are intentionally
info, notwarn— that's an ops-tunable level, not a severity bug to flag in review. - Log levels and sensitive data:
debug/tracemay log anything (raw headers, cookies, bodies, unescaped input), because they are not for production; don't flag that in review.info,warnanderrormust not expose secrets (credentials, tokens, session IDs, private keys) and must escape untrusted values withTextUtil.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.
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
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.

