docs: add CLAUDE.md (AI-contributor guardrails) + CLAUDE_USER_EXAMPLE.md#343
Open
MichaelLeeHobbs wants to merge 1 commit into
Open
Conversation
…EXAMPLE.md
CLAUDE.md: strict guidance for AI coding assistants working on the engine itself,
designed to protect the project from low-quality sprawling AI changes ("vibeslop").
- Push-back-first: for non-trivial work, state the change + any concrete disagreement
+ a better alternative BEFORE editing (calibrated to blast radius, so no theater).
- Anti-sprawl bounded in breadth AND depth (<=3 files; ~40-50 line / whole-method cap).
- Preserve behavior/compat incl. the subtle breaks (charset, tz/locale, HL7 delimiters);
golden-output test for donkey/serialization changes; red-green regression tests.
- Healthcare security: no PHI logging; no unsafe deserialization/XXE (documented RCE class).
- Issue-first-and-wait; MPL header copied from server/license-header.txt; no slop tells.
- Grounded in the repo (Java 17 + Ant server/mirth-build.xml, module map, CONTRIBUTING).
- No orchestration skill by design. Advisory; notes which gates belong in CI.
CLAUDE_USER_EXAMPLE.md: a copy-me starter CLAUDE.md for a user's own channel/template
repo (JS on the Rhino runtime) — Rhino/ES5 constraints, loop-scoping bug, Java interop,
engine globals, code patterns; points at oie-examples and the docs site.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
MichaelLeeHobbs
requested review from
a team,
Copilot,
gibson9583,
kayyagari,
kpalang,
mgaffigan,
pacmano1,
ssrowe and
tonygermano
There was a problem hiding this comment.
Pull request overview
Adds repository documentation intended to guide AI-assisted contributions and provide a copyable starter template for users writing OIE channel/template JavaScript.
Changes:
- Adds
CLAUDE.mdat the repo root with guardrails for AI-assisted work on the engine codebase. - Adds
CLAUDE_USER_EXAMPLE.mdas a copy-me starterCLAUDE.mdfor user-owned channel/template JavaScript repositories.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
CLAUDE.md |
Documents AI-contributor guardrails and contribution/build expectations for engine changes. |
CLAUDE_USER_EXAMPLE.md |
Provides a user-repo template describing Rhino/JS constraints and recommended patterns for deployed scripts. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+81
to
+83
| - **Build + test** (what CI runs off `main`): `cd server && ant -f mirth-build.xml -DdisableSigning=true -Dcoverage=true` | ||
| (the signed build drops the flags and runs on `main`). JUnit results land under | ||
| `*/build/test-results/**/*.xml`. **A red build is not reviewable — never open a PR on one.** |
Comment on lines
+54
to
+74
| ### Supported ES6 features (safe to use) | ||
| - `const` and `let` — prefer over `var`. `const` by default, `let` when reassignment is needed (but see the | ||
| Rhino loop-scoping bug below). | ||
| - Arrow functions `() => {}` — fine in callbacks, `.map()`, `.filter()`, etc. | ||
| - Object/array destructuring — `const { a, b } = options` | ||
| - `Object.keys()`, `Object.values()`, `Object.entries()`, `Object.assign()` | ||
| - Array methods: `.map()`, `.filter()`, `.reduce()`, `.forEach()`, `.find()`, `.some()`, `.every()` | ||
|
|
||
| ### Prohibited ES6+ features (will break at runtime in OIE) | ||
| - **Template literals** — NEVER use backtick strings. `` `Hello ${name}` `` fails at runtime. Use string | ||
| concatenation or `Array.join()` (see "String building"). | ||
| - **Optional chaining `?.`** — not supported; use a try/catch helper (see "Safe property access"). | ||
| - **Nullish coalescing `??`** — use `||` or an explicit ternary. | ||
| - **`async`/`await`** — not supported. Transformers are synchronous; use callbacks/retries. | ||
| - **`Promise`** — not available in the runtime. | ||
| - **ES6 classes (`class`/`extends`)** — use constructor functions with `.prototype` methods. | ||
| - **ES6 modules (`import`/`export`)** — share code via Code Templates plus `/* global */` and | ||
| `/* exported */` comments (see "Module/export pattern"). | ||
| - **Spread syntax `...args`** — minimal/unreliable support; avoid, especially in parameter lists. | ||
| - **`for...of` loops** — use `.forEach()` or a traditional indexed `for` loop. | ||
| - **Default parameters** — use `param = param || defaultValue` instead. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #342.
Adds two documentation files to help contributors who use AI coding assistants.
CLAUDE.md(repo root) — guardrails for AI-assisted work on the engineDesigned to keep AI contributions small, reviewable, and from degrading code quality in a production healthcare engine:
donkey//serialization changes.ObjectInputStream) / XXE, referencing this codebase's documented RCE history.server/license-header.txt, no slop tells.server/mirth-build.xml), the module map, andCONTRIBUTING.md. No orchestration/automation skill by design. Advisory — it also notes which rules belong in CI/PR-template as hard gates.CLAUDE_USER_EXAMPLE.md— starter for a user's own channel/template repoA copy-me
CLAUDE.mdfor JavaScript that runs on the Rhino runtime: ES5/Rhino constraints, the loop-scoping bug, Java-interop gotchas, engine globals, and code patterns. Points atoie-examplesand the docs site. (Could alternatively live inoie-examples— happy to move it.)Disclosure
Both files were drafted with AI assistance (Claude Code). The content reflects my years of hands-on Mirth/Connect experience and research, and I have reviewed both in full and stand behind them. Feedback and scope changes welcome.