docs: Add agent instructions and skills#10612
Conversation
Adds .claude/skills/testing-parse-server with the repo-specific verification rules (build lib/ before running specs, run affected specs in isolation, test both MongoDB and Postgres, drive a live server and inspect stored state) and an appendable GOTCHAS list. Narrows the .claude ignore rule so shared skills are tracked while local settings stay ignored.
Adds a tool neutral AGENTS.md covering the build and test commands, the lib/ build step specs run against, the dual backend requirement, spec isolation, scope and code quality expectations, and the pull request conventions. CLAUDE.md and .github/copilot-instructions.md are symlinks to it so there is one copy. Expands the testing skill with verification levels, the guard proof, what CI runs, and test isolation rules.
…ormance guidance Split the skill into focused references: verification procedure, security probing, performance measurement, adversarial QA and a command reference. Facts checked against package.json, spec/helper.js, the CI workflows and src/, and corrected where the previous version was wrong.
|
🚀 Thanks for opening this pull request! We appreciate your effort in improving the project. Please let us know once your pull request is ready for review. Tip
Note Please respond to review comments from AI agents just like you would to comments from a human reviewer. Let the reviewer resolve their own comments, unless they have reviewed and accepted your commit, or agreed with your explanation for why the feedback was incorrect. Caution Pull requests must be written using an AI agent with human supervision. Pull requests written entirely by a human will likely be rejected, because of lower code quality, higher review effort and the higher risk of introducing bugs. Please note that AI review comments on this pull request alone do not satisfy this requirement. Our CI and AI review are safeguards, not development tools. If many issues are flagged, rethink your development approach. Invest more effort in planning and design rather than using review cycles to fix low-quality code. |
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@coderabbitai review |
✅ Action performedReview finished.
|
Adds two task skills alongside the testing one: adding-a-server-option covers the generated Options files, the hand-maintained types/Options/index.d.ts and the security-check question; changing-behaviour-safely covers judging whether a change is breaking, client SDK and API-surface compatibility, and the deprecation mechanism. Promotes scope discipline in AGENTS.md to its own section.
dblythy
changed the title
1 participant
Pull Request
Issue
Closes #10611
AI coding agents working on this repo repeatedly hit the same traps: they edit
src/, run the specs against a stalelib/, and report a green suite as proof the change works. They test Mongo only, skip the guard-proof, hand-edit generated files, and treat a default change as a routine improvement. Nothing in the repo told them otherwise.Approach
Adds
AGENTS.md(what Parse Server is, how a request flows, where things live, scope discipline, repo conventions) and three tracked agent skills under.claude/skills/.testing-parse-server/— verification, split by concern: the build-before-test rule and a table of what each type of change demands (SKILL.md); the procedure, including guard-proofing a spec against the unfixed code and inspecting stored state (VERIFICATION.md); the recurring attack primitives behind past advisories (SECURITY.md); complexity review and benchmark comparison (PERFORMANCE.md); coverage gaps and edge probing (ADVERSARIAL-QA.md); commands, env vars and harness globals (REFERENCE.md); and an appendable trap log (GOTCHAS.md).adding-a-server-option/— the most repeated change in the repo.src/Options/index.jsis the only file edited by hand;Definitions.jsanddocs.jsare generated and CI diffs them;types/Options/index.d.tsis the one manually-maintained.d.ts; nested groups need registering inresources/buildConfigDefinitions.jsor their env vars silently do nothing; and an option that can weaken a deployment needs a security check.changing-behaviour-safely/— whether a change is breaking and how to avoid it, the compatibility surfaces (client SDKs,ClientSDKversion-gating, REST/GraphQL/LiveQuery/batch parity, and data already in deployments' databases), and the deprecation mechanism.Content is derived from the repo rather than written from memory, and checked against
package.json,spec/helper.js,src/Options/,resources/buildConfigDefinitions.js,ci/definitionsCheck.js,src/Deprecator/,src/ClientSDK.js,src/Security/CheckGroups/and the CI workflows. Three findings worth flagging for reviewers, all verified in source:PARSE_SERVER_LOG_LEVEL=debugdoes not produce debug-level logs inside specs.spec/helper.jspassesverbose: !silent, andconfigureLoggerappliesif (verbose) logLevel = 'verbose'last, overriding it. It still enables the Postgres SQL tracer, which reads the env var directly inPostgresClient.js.npm run docsrenderslib/, notsrc/—jsdoc-conf.jsonincludes./lib/Options/docs.jsand there is nopredocshook, so a newly generated option is absent from the output unlessnpm run buildruns first.ci-performance.yml, both the >25% and >50% regression bands sethasRegressionand fail the job; the difference is only the printed label.The option workflow was dry-run end to end against the repo to confirm the documented behaviour (generation, the derived env var name, and that
ci:definitionsCheckfails on a stale generated file), then reverted.Docs only, no runtime code touched.
Tasks