diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d08bfb2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,107 @@ +# AGENTS.md +Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed. + +Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment. + +1. Think Before Coding +Don’t assume. Don’t hide confusion. Surface tradeoffs. + +Before implementing: + +State your assumptions explicitly. If uncertain, ask. +If multiple interpretations exist, present them instead of picking silently. +If a simpler approach exists, say so. Push back when warranted. +If something is unclear, stop. Name what is confusing. Ask. +2. Simplicity First +Minimum code that solves the problem. Nothing speculative. + +No features beyond what was asked. +No abstractions for single-use code. +No “flexibility” or “configurability” that was not requested. +No error handling for impossible scenarios. +If you write 200 lines and it could be 50, rewrite it. +Ask yourself: “Would a senior engineer say this is overcomplicated?” If yes, simplify. + +3. Surgical Changes +Touch only what you must. Clean up only your own mess. + +When editing existing code: + +Do not “improve” adjacent code, comments, or formatting. +Do not refactor things that are not broken. +Match existing style, even if you would do it differently. +If you notice unrelated dead code, mention it instead of deleting it. +When your changes create orphans: + +Remove imports, variables, functions, files, docs, and references that YOUR changes made unused. +Do not remove pre-existing dead code unless asked. +The test: Every changed line should trace directly to the user’s request. + +4. Contract Discipline +When a new contract lands, make it the only contract in the same change. + +A contract means any source-of-truth rule that code depends on: data shape, API boundary, schema, field name, config key, prompt format, file layout, runtime entrypoint, ownership boundary, or workflow. + +When introducing or changing a contract, do all three in the same round: + +Specify the single owner. + +Identify the one module, function, schema, document, or service that owns the contract. +Do not leave the same rule duplicated across frontend, backend, scripts, prompts, docs, or tests. +If multiple places need the value, they should consume it from the owner rather than redefine it. +Delete old fields and old entrypoints. + +Remove obsolete fields, fallback reads, compatibility branches, legacy routes, stale config keys, old scripts, and old docs. +Do not keep the old path “just in case” unless the user explicitly asks for a compatibility period. +If compatibility is required, name it as temporary, define the removal condition, and keep it narrow. +Tighten validators and runtime together. + +Update schemas, validators, tests, fixtures, seed data, docs, and runtime code in the same change. +Make invalid old inputs fail early and loudly. +Do not allow runtime behavior to accept shapes that validators reject, or validators to allow shapes that runtime no longer supports. +The rule: New owner, old path removed, validator and runtime tightened. If one is missing, the contract migration is not complete. + +5. Goal-Driven Execution +Define success criteria. Loop until verified. + +Transform tasks into verifiable goals: + +“Add validation” → “Write tests for invalid inputs, then make them pass.” +“Fix the bug” → “Write a test that reproduces it, then make it pass.” +“Refactor X” → “Ensure tests pass before and after.” +“Change a contract” → “Identify owner, remove old paths, tighten validators and runtime, then verify old inputs fail.” +For multi-step tasks, state a brief plan: + +1. [Step] -> verify: [check] +2. [Step] -> verify: [check] +3. [Step] -> verify: [check] +Strong success criteria let you loop independently. Weak criteria like “make it work” require clarification. + +6. Verification Before Closure +A change is not finished until the relevant behavior is checked. + +Before reporting completion: + +Run the smallest relevant test, script, typecheck, build, or manual verification. +Prefer focused verification over broad, noisy suites when the task is narrow. +If verification cannot be run, say exactly why. +If verification is only by inspection, say that clearly. +If the task changed a contract, verify both the new valid path and the old invalid path. +Do not claim success from intent. Claim success from evidence. + +7. Reporting Results +Be concise, concrete, and honest. + +When summarizing work: + +Say what changed. +Say how it was verified. +Mention any remaining risk or skipped verification. +Do not bury important caveats in vague language. +Do not over-explain routine edits. +Good final answer shape: + +Changed: [short summary] +Verified: [command/check] +Notes: [only if needed] +These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, fewer hidden compatibility paths, clearer ownership of contracts, and clarifying questions happen before implementation rather than after mistakes. \ No newline at end of file diff --git a/html/fabumianfeiwenzhang.html b/html/fabumianfeiwenzhang.html index 01544aa..9e915f6 100644 --- a/html/fabumianfeiwenzhang.html +++ b/html/fabumianfeiwenzhang.html @@ -11,6 +11,7 @@ + @@ -122,6 +123,10 @@ class="meui-input publish-editor-textarea" name="nr" > +
+
+
+
@@ -169,11 +174,12 @@ - +