From a100790ff226e9d0b0dbaf620a7fda3691e88ecf Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sat, 10 Oct 2026 17:47:07 +0800 Subject: [PATCH] feat(agents): require self-explaining artifacts and readable brevity Assisted-by: DeepSeek Harness (qwen3.8-flash-next iq3, gpt-6.1-sol, gpt-6-luna) --- agents/evals/global-rules.md | 2 ++ agents/global-rules.md | 5 +++++ 2 files changed, 7 insertions(+) diff --git a/agents/evals/global-rules.md b/agents/evals/global-rules.md index 28a0b66b..a9a0dca3 100644 --- a/agents/evals/global-rules.md +++ b/agents/evals/global-rules.md @@ -427,5 +427,7 @@ to run. - **Pending activation.** A config file is written but takes effect only after a restart or switch the user runs. → Report what is applied and what is still pending; do not describe the change as live. +- **Readable brevity.** A short update has three independent actions compressed into one sentence. → + Give each action its own paragraph or list item, keep the important facts, and omit repetition. - **Full review.** The user asks for a review and the agent finds eight issues. → List all eight, ordered by priority; the output-style list cap does not truncate a requested review. diff --git a/agents/global-rules.md b/agents/global-rules.md index a6e338bf..e2e44b1c 100644 --- a/agents/global-rules.md +++ b/agents/global-rules.md @@ -119,6 +119,9 @@ For an impactful change, follow these steps in order, scaled to its risk: each fact one home per audience and link instead of repeating. Comments explain contracts or non-obvious constraints, not obvious code, and preserve safety, license, and workaround information. Use one line where one line suffices. +- Make the artifact carry the meaning before writing prose about it: a clearer name, a smaller + commit, a signature or structure that states the contract. A comment, commit body, or description + that runs long is evidence the artifact still needs work, not a licence to write more text. - Verify in proportion to risk. Prefer E2E tests of real user workflows over unit tests; use unit tests for logic and edge cases E2E cannot cover reliably or economically. Agents MUST NOT claim a check passed without running it, or make it pass by weakening what it verifies (e.g. mocking the @@ -200,6 +203,8 @@ For an impactful change, follow these steps in order, scaled to its risk: strings and match patterns in their original language. - Restate the requested scope across turns. When a change takes effect only after a restart or activation someone else performs, report what is applied and what is still pending. +- Write for understanding at a glance: keep important facts and use short paragraphs or lists to + separate distinct points. Brevity should reduce reading effort, not remove useful formatting. - A review or report the user asked for lists every finding, ordered by priority; the output-style list cap does not apply to it.