From ef41e3b335232687dbd74c19a3ab08f621ac1a55 Mon Sep 17 00:00:00 2001 From: Notorious Date: Thu, 9 Apr 2026 11:37:38 +0800 Subject: [PATCH] docs: add AI-assisted contributions guidelines and sample agent prompt Set expectations for AI-generated contributions: require human review before requesting PR review, remove verbosity and redundancy, verify payment/signing correctness against specs, and disclose significant AI usage. Include a sample system prompt for AI coding agents (Claude Code, Codex, Cursor) that aligns agent output with x402 contribution standards. Inspired by Neovim's AI-assisted work guidelines, adapted for x402's security-sensitive payment infrastructure context. --- CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 578b61e1f1..6e8beb1b19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,7 @@ x402 welcomes contributions of schemes, middleware, new chain support, and more. ## Contents +- [AI-Assisted Contributions](#ai-assisted-contributions) - [Repository Structure](#repository-structure) - [Language-Specific Guides](#language-specific-guides) - [Contributing Workflow](#contributing-workflow) @@ -11,6 +12,66 @@ x402 welcomes contributions of schemes, middleware, new chain support, and more. - [Commit Signing](#commit-signing) - [Getting Help](#getting-help) +## AI-Assisted Contributions + +Using AI tools (LLMs, code assistants, etc.) for contributions is acceptable, given the following: + +- **You must review AI output before requesting review.** Do not open a non-Draft PR until you have personally verified the generated code. AI-generated PRs submitted without human review waste maintainer time and erode trust. +- **Remove verbosity and filler.** AI tools tend to produce verbose documentation, comments, PR descriptions, and commit messages. Strip these down to what is concise, clear, and useful — nothing more. +- **Remove redundant code and tests.** Deduplicate generated code, tests, and explanations. Explicitness and clarity are good; repetition and over-explanation are not. +- **Verify correctness, especially around payment and signature logic.** x402 handles real value transfer. AI tools hallucinate plausible-looking code that may be subtly wrong — incorrect signing flows, wrong chain constants, hallucinated headers that don't match the spec. You are responsible for catching these before submission. +- **Do not batch-generate low-effort PRs.** Submitting multiple narrow, machine-generated PRs in rapid succession is obvious and unhelpful. If AI helps you work faster, use that speed to produce fewer, higher-quality contributions — not more low-quality ones. +- **Disclose significant AI usage.** If the majority of a PR was generated by an AI tool, note this in the PR description. This is not a mark against the PR — it helps reviewers calibrate their review (e.g., checking for hallucinated APIs or fabricated test assertions). + +Contributions that show clear signs of unreviewed AI output (generic filler comments, hallucination, redundant boilerplate, cookie-cutter PR descriptions) may be closed without detailed review. + +### Sample Prompt for AI-Assisted Development + +If you use an AI coding agent (Claude Code, Codex, Cursor, etc.) to work on x402, include the following in your agent's system prompt or project instructions. This ensures the agent's output aligns with x402 contribution standards before you review it. + +```text +You are contributing to x402, an open protocol for internet-native payments. +x402 handles real value transfer — correctness is critical. + +Follow these rules for all code, documentation, and commit messages you produce: + +1. CONCISE OUTPUT ONLY. Do not add filler comments, redundant docstrings, or + verbose explanations. Every line of documentation or commentary must carry + useful information. + +2. NO REDUNDANCY. Do not generate duplicate or near-duplicate code, tests, or + explanations. If logic already exists, use it — do not rewrite it. Three + similar lines are better than an unnecessary abstraction, but three identical + blocks are never acceptable. + +3. VERIFY AGAINST THE SPEC. Before writing payment, signing, or settlement + logic, read the relevant spec in specs/. Do not invent header names, payload + fields, or signing flows. If you are unsure whether a field or constant + exists, search the codebase — do not guess. + +4. MATCH EXISTING PATTERNS. Read the surrounding code before generating new + code. Match the style, naming conventions, error handling, and test patterns + already in use for that SDK (TypeScript, Python, Go, or Java). + +5. DO NOT ADD UNREQUESTED FEATURES. Implement exactly what was asked. Do not + add extra configuration options, feature flags, helper utilities, or + "improvements" beyond the scope of the task. + +6. COMMIT MESSAGES. Use conventional commits (feat:, fix:, docs:, chore:). + Keep the subject line under 72 characters. The body should explain why, not + what — the diff shows what changed. + +7. CHAIN AND TOKEN CONSTANTS. Never hardcode chain IDs, token addresses, or + decimal values from memory. Always reference the constants defined in the + codebase (e.g., mechanisms/evm/constants, mechanisms/svm/constants). + +8. TEST CORRECTNESS. Generated tests must assert meaningful behavior, not just + that "the function doesn't throw." Do not fabricate expected values — derive + them from the spec or existing test fixtures. +``` + +You can place this in a `CLAUDE.md`, `.cursorrules`, `codex-instructions.md`, or equivalent file at the root of your working copy. It is not committed to the repository — it is for your local development workflow. + ## Repository Structure The x402 repository contains implementations in multiple languages plus protocol specifications.