Skip to content

Adonis0123/adonis-skills / skills/agent-practice-audit

agent-practice-audit

Flagged

Score how someone uses coding agents (Claude Code, Codex, Grok and WorkBuddy session logs, instruction files, hooks, permissions, Codex config) against practices quoted from official vendor docs, and write a local HTML report with coverage, trend and suggestions; also refresh or verify that practice list from official docs with multi-model consensus. Use when the user asks how far their agent usage is from official practice, wants an agent usage check-up or grade, or wants the practice list refreshed, its links checked, or either run on a schedule. Chinese triggers: Agent 用法体检、对照官方最佳实践、我的 agent 用得对不对、给 agent 用法打分、更新最佳实践清单. Not for whether a tool, MCP or skill is worth keeping (dev-environment-roi-audit), for writing or reviewing one CLAUDE.md or AGENTS.md, for general best-practice questions, or for Cursor or Gemini CLI logs, which it does not read. Never edits the user's config.

FileKindSize
SKILL.mdskill md18.3 KB
assets/default-config.jsonconfig352 B
assets/img/hero.webpbinary106.5 KB
assets/img/nika-wordmark-white.svgother490 B
assets/img/nika-wordmark.svgother490 B
assets/report-template.htmlother41.2 KB
evals/evals.jsonconfig844 B
evals/trigger-eval-set.jsonconfig1.6 KB
references/audit-files.mdmarkdown32.2 KB
references/changelog.mdmarkdown7.2 KB
references/practices.jsonconfig37.3 KB
references/scheduling.mdmarkdown11.9 KB
references/sources.mdmarkdown6.5 KB
references/sources/cc-art-loops.mdmarkdown1.7 KB
references/sources/cc-art-maximizing-sessions.mdmarkdown1.9 KB
references/sources/cc-art-opus-5-5-context.mdmarkdown1.4 KB
references/sources/cc-art-sdlc-playbook.mdmarkdown1.9 KB
references/sources/cc-art-steering.mdmarkdown1.9 KB
references/sources/cc-art-verification-loops.mdmarkdown1.6 KB
references/sources/cc-best-practices.mdmarkdown3.0 KB
references/sources/cc-common-workflows.mdmarkdown1.7 KB
references/sources/cc-costs.mdmarkdown2.3 KB
references/sources/cc-memory.mdmarkdown1.7 KB
references/sources/codex-agents-md.mdmarkdown1.5 KB
references/sources/codex-best-practices.mdmarkdown2.6 KB
references/sources/codex-non-interactive.mdmarkdown1.3 KB
references/sources/codex-sandboxing.mdmarkdown1.4 KB
references/sources/cursor-agent-best-practices.mdmarkdown1.8 KB
references/verify-prompt.mdmarkdown4.6 KB
scripts/aggregate.pyscript22.3 KB
scripts/audit_common.pyscript8.6 KB
scripts/build_report.pyscript30.8 KB
scripts/check_practices.pyscript24.8 KB
scripts/config_scan.pyscript28.3 KB
scripts/consensus.pyscript38.1 KB
scripts/digests.pyscript10.2 KB
scripts/export_metrics.pyscript10.3 KB
scripts/extract.pyscript42.5 KB
scripts/prejudge.pyscript41.8 KB
scripts/run_audit.pyscript3.8 KB
scripts/safe_output.pyscript2.0 KB
scripts/test_agent_practice_audit.pyscript81.1 KB
scripts/test_consensus_run.pyscript26.9 KB
scripts/test_measurement.pyscript68.7 KB
scripts/test_prejudge.pyscript24.2 KB

references/practices.json

View on GitHub
{
  "version": 2,
  "updatedAt": "2026-11-11",
  "dimensions": {
    "ctx": {
      "en": "Context management",
      "zh": "上下文管理",
      "hint": {
        "en": "session length, /clear, subagent offload",
        "zh": "会话长度、/clear、subagent 分流"
      }
    },
    "safe": {
      "en": "Permissions & safety",
      "zh": "权限与安全",
      "hint": {
        "en": "sandbox, deny rules, size of the enforced set",
        "zh": "沙箱、deny、强制规则数量"
      }
    },
    "doc": {
      "en": "Instruction files",
      "zh": "指令文件",
      "hint": {
        "en": "AGENTS.md / CLAUDE.md length and content",
        "zh": "AGENTS.md 长度和内容"
      }
    },
    "plan": {
      "en": "Think before doing",
      "zh": "先想后做",
      "hint": {
        "en": "plan mode, interviews, done criteria",
        "zh": "plan 模式、访谈、完成标准"
      }
    },
    "verify": {
      "en": "Verification",
      "zh": "验证",
      "hint": {
        "en": "tests, screenshots, evidence",
        "zh": "测试、截图、证据"
      }
    },
    "auto": {
      "en": "Parallelism & automation",
      "zh": "并行与自动化",
      "hint": {
        "en": "worktrees, headless runs, limits",
        "zh": "worktree、headless、上限"
      }
    }
  },
  "practices": [
    {
      "id": "ctx-clear-between-tasks",
      "dimension": "ctx",
      "title": "Clear context between unrelated tasks",
      "title_zh": "无关任务之间用 /clear 清空上下文",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "/clear between unrelated tasks. It costs nothing…",
          "fragment": "between unrelated tasks"
        },
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "after two failed corrections run /clear and write a better prompt instead of a third",
          "fragment": "after two failed corrections run"
        },
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "Keep one chat per coherent unit of work.",
          "fragment": "Keep one chat per coherent unit of work"
        }
      ],
      "detect": "Summary: long_sessions, corrections_per100_prompts vs cohorts.long.corr_per100, cohorts.long.cleared (a new human session in the same directory, any account or host, handoffs included), pct_started_by_clear.",
      "rule": {
        "text": "Proxy: relatedness is not logged; one long task is fine. Long = over 200 tool calls. Cleared = a new human session (/clear, /new, other account or host, handoff) in the same directory within 10 min of its end. ok: <10% long, or >=20% of long sessions cleared; part: >=30% long and more corrections per prompt when long (hosts with >=10 long); else na (heuristic)",
        "params": {
          "long_tools": 200,
          "long_ok_pct": 10,
          "long_part_pct": 30,
          "clear_ok_pct": 20,
          "min_long": 10,
          "clear_gap_minutes": 10
        }
      },
      "fix_kind": "habit",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "ctx-subagent-offload",
      "dimension": "ctx",
      "title": "Send verbose exploration to subagents so only a summary returns",
      "title_zh": "输出多的工作交给 subagent",
      "sources": [
        {
          "source": "cc-costs",
          "page": "Claude Code costs",
          "url": "https://code.claude.com/docs/en/costs",
          "quote": "the verbose output stays in the subagent's context while only a summary returns to your main conversation.",
          "fragment": "the verbose output stays in the subagent"
        },
        {
          "source": "cc-common-workflows",
          "page": "Claude Code common workflows",
          "url": "https://code.claude.com/docs/en/common-workflows",
          "quote": "Delegate the exploration so only the findings come back.",
          "fragment": "Delegate the exploration so only the findings come back"
        }
      ],
      "detect": "Summary: cohorts.wide (reads include linked subagent transcripts), agent_types_calls.",
      "rule": {
        "text": "Cohort: human sessions with >=30 read/search calls, linked subagent reads included. Offloaded = a linked subagent did reads itself (any subagent call if the host links none); only its final message returns. ok: offloaded in >=20%; part: some; no: none; na: <10 in cohort (heuristic)",
        "params": {
          "wide_explore": 30,
          "min_cohort": 10,
          "ok_pct": 20
        }
      },
      "fix_kind": "habit",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "ctx-custom-subagents",
      "dimension": "ctx",
      "title": "Give simple subagents a cheaper model (model: haiku)",
      "title_zh": "简单的 subagent 用便宜模型(model: haiku)",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "Set model: haiku in a subagent's definition if its work is simple",
          "fragment": "if its work is simple"
        },
        {
          "source": "cc-costs",
          "page": "Claude Code costs",
          "url": "https://code.claude.com/docs/en/costs",
          "quote": "For simple subagent tasks, specify model: haiku in your subagent configuration.",
          "fragment": "For simple subagent tasks"
        }
      ],
      "detect": "Config: claude[] / claude_projects[] custom_subagents; the judge reads agents/*.md for a model field.",
      "rule": {
        "text": "na without agents/*.md definitions. Else semantic (logs do not show which work is simple): ok: every simple-looking definition sets model: haiku or another smaller model; part: some; no: none; na: none looks simple.",
        "params": {}
      },
      "fix_kind": "config",
      "verifiedAt": "2026-11-11",
      "basis": "live",
      "consensus": {
        "verifiers": ["codex", "grok"],
        "agree": 2,
        "total": 2,
        "checkedAt": "2026-11-11"
      }
    },
    {
      "id": "ctx-compact-focus",
      "dimension": "ctx",
      "title": "Tell /compact what to keep, or put Compact instructions in CLAUDE.md",
      "title_zh": "/compact 时说明要保留什么,或在 CLAUDE.md 写 Compact instructions",
      "sources": [
        {
          "source": "cc-costs",
          "page": "Claude Code costs",
          "url": "https://code.claude.com/docs/en/costs",
          "quote": "/compact Focus on code samples and API usage tells Claude what to preserve during summarization.",
          "fragment": "tells Claude what to preserve during summarization"
        },
        {
          "source": "cc-costs",
          "page": "Claude Code costs",
          "url": "https://code.claude.com/docs/en/costs",
          "quote": "You can also customize compaction behavior in your CLAUDE.md file at the root of your project",
          "fragment": "customize compaction behavior in your CLAUDE.md file"
        }
      ],
      "detect": "Summary: hosts.<h>.compact_cmds, compact_focus (/compact with arguments); config: instruction files' compact_instructions (heading), compact_notes.",
      "rule": {
        "text": "ok: a 'Compact instructions' heading, or >=50% of typed /compact commands with a focus; part: some with a focus, or compaction notes without the heading; no: >=3 typed /compact, none with a focus, no heading or notes; else na. Auto-compaction is not judged (heuristic)",
        "params": {
          "focus_ok_pct": 50,
          "min_compacts": 3
        }
      },
      "fix_kind": "config",
      "verifiedAt": "2026-11-11",
      "basis": "live",
      "consensus": {
        "verifiers": ["codex", "grok"],
        "agree": 2,
        "total": 2,
        "checkedAt": "2026-11-11"
      }
    },
    {
      "id": "safe-low-risk-preset",
      "dimension": "safe",
      "title": "Keep approvals and sandboxing tight by default; give full access only as an exception",
      "title_zh": "审批和沙箱默认收紧,全权限只作例外",
      "sources": [
        {
          "source": "codex-sandboxing",
          "page": "Codex sandboxing",
          "url": "https://learn.chatgpt.com/docs/sandboxing.md",
          "quote": "the lower-risk local automation preset is sandbox_mode = \"workspace-write\" together with approval_policy = \"on-request\"",
          "fragment": "the lower-risk local automation preset is"
        },
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "Giving Codex full permission to your computer before you understand the workflow",
          "fragment": "Giving Codex full permission to your computer"
        },
        {
          "source": "codex-non-interactive",
          "page": "Codex non-interactive mode",
          "url": "https://learn.chatgpt.com/docs/non-interactive-mode",
          "quote": "Use danger-full-access only in a controlled environment",
          "fragment": "only in a controlled environment"
        },
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "Keep approval and sandboxing tight by default, then loosen permissions only for trusted repos or specific workflows once the need is clear.",
          "fragment": "Keep approval and sandboxing tight by default"
        }
      ],
      "detect": "Summary: full_access_sessions, modes_sessions; config: codex[].approval_policy / sandbox_mode.",
      "rule": {
        "text": "Full access = no approval and no sandbox in one turn (Claude bypass, Grok yolo, Codex never + danger-full-access); today's sandbox is not applied to past sessions. Trusted repos and controlled environments, where the pages allow it, are not logged, so: ok: <20% of human sessions; part: 20-49%; no: >=50%, full access as the default (heuristic)",
        "params": {
          "ok_below_pct": 20,
          "no_pct": 50
        }
      },
      "fix_kind": "config",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "safe-hooks-for-musts",
      "dimension": "safe",
      "title": "Make rules that must hold every time a hook, a deny rule or a managed setting",
      "title_zh": "每次都必须执行的规则交给 hook、deny 规则或 managed setting",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "If something has to happen every time, make it a hook, a deny rule, or a managed setting.",
          "fragment": "If something has to happen every time"
        }
      ],
      "detect": "Config: instruction files' must_rules, must_topics; claude[] / claude_projects[] hook_topics (every hook, by matcher and command), deny_topics. Managed settings are not scanned.",
      "rule": {
        "text": "Must-word lines (always, never, must, 必须...) stand in for 'has to happen every time'; topics (the audit's matcher): secrets, destructive, git_push, language. na without must lines. ok: every topic has a hook (any event) or deny rule; part: some, or hooks or denies on other topics; no: neither. A managed setting the user names counts.",
        "params": {}
      },
      "fix_kind": "config",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "safe-small-enforced-set",
      "dimension": "safe",
      "title": "Keep the enforced set (hooks + deny rules) small",
      "title_zh": "强制规则(hook + deny)保持少量",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "Whatever the scope, keep the enforced set small. … If you ever find yourself at forty of them, most are probably preferences",
          "fragment": "Whatever the scope, keep the enforced set small"
        }
      ],
      "detect": "Config: hook_entries + deny_count per active setup.",
      "rule": {
        "text": "Every hook entry plus every deny rule in the largest active setup. ok: <20; part: 20-39; no: >=40 (heuristic)",
        "params": {
          "ok_below": 20,
          "no_from": 40
        }
      },
      "fix_kind": "config",
      "verifiedAt": "2026-11-11",
      "basis": "live",
      "consensus": {
        "verifiers": ["codex", "grok"],
        "agree": 2,
        "total": 2,
        "checkedAt": "2026-11-11"
      }
    },
    {
      "id": "safe-deny-secrets",
      "dimension": "safe",
      "title": "Protect .env and secret files with deny rules",
      "title_zh": "用 deny 规则保护 .env 和密钥文件",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "deny rules hold in every permission mode, including auto and bypassPermissions, which is exactly why the .env rule belongs there",
          "fragment": "rules hold in every permission mode"
        }
      ],
      "detect": "Config: settings deny_coverage (path-like rules only); modes_sessions for context.",
      "rule": {
        "text": "Path-like deny rules only. ok: .env files covered; part: only other secret paths (secrets/, key files, ~/.ssh, ~/.aws, cloud); no: none. The worst active setup decides (deny rules hold in every mode).",
        "params": {}
      },
      "fix_kind": "config",
      "verifiedAt": "2026-11-11",
      "basis": "live",
      "consensus": {
        "verifiers": ["codex", "grok"],
        "agree": 2,
        "total": 2,
        "checkedAt": "2026-11-11"
      }
    },
    {
      "id": "doc-short-instructions",
      "dimension": "doc",
      "title": "Keep AGENTS.md / CLAUDE.md short",
      "title_zh": "AGENTS.md / CLAUDE.md 保持短小",
      "sources": [
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "A short, accurate AGENTS.md is more useful than a long file full of vague rules.",
          "fragment": "is more useful than a long file full of vague rules"
        },
        {
          "source": "cc-memory",
          "page": "Claude Code memory",
          "url": "https://code.claude.com/docs/en/memory",
          "quote": "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.",
          "fragment": "target under 200 lines per"
        },
        {
          "source": "codex-agents-md",
          "page": "Codex AGENTS.md",
          "url": "https://learn.chatgpt.com/docs/agent-configuration/agents-md",
          "quote": "stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default)",
          "fragment": "stops adding files once the combined size reaches the limit"
        }
      ],
      "detect": "Config: CLAUDE.md line counts (symlinks too); codex[].instruction_chain_bytes_max (repo AGENTS chain, root down) vs project_doc_max_bytes.",
      "rule": {
        "text": "part: a CLAUDE.md over 200 lines, or Codex's repository AGENTS chain over project_doc_max_bytes (default 32768 bytes = 32 KiB), where Codex stops adding files; ok: neither. No 'no': raising the cap is allowed.",
        "params": {
          "line_target": 200,
          "codex_doc_bytes": 32768
        }
      },
      "fix_kind": "config",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "doc-test-commands",
      "dimension": "doc",
      "title": "Put the commands that run your checks (build, test, lint) in the instruction file",
      "title_zh": "把跑检查的命令(build、test、lint)写进指令文件",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "the single most useful line in your CLAUDE.md is the command that runs it.",
          "fragment": "the single most useful line in your"
        },
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "Build, test, and lint commands",
          "fragment": "Build, test, and lint commands"
        }
      ],
      "detect": "Config: repo_instructions[].mentions_test / mentions_build / mentions_lint (real commands), grouped by repo (root and subdirectory AGENTS.md / CLAUDE.md; global files exempt).",
      "rule": {
        "text": "Per repository. Check command = test, build, lint or typecheck (Claude: the command for whatever check exists; Codex lists build, test, lint). ok: every repository names one; part: some; no: none. Missing build/test/lint is listed, not scored.",
        "params": {}
      },
      "fix_kind": "config",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "doc-update-on-repeat",
      "dimension": "doc",
      "title": "Update the rules when the same mistake happens twice",
      "title_zh": "同一错误出现两次就更新规则",
      "sources": [
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "When Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md.",
          "fragment": "When Codex makes the same mistake twice"
        },
        {
          "source": "cursor-agent-best-practices",
          "page": "Cursor agent best practices",
          "url": "https://cursor.com/blog/agent-best-practices",
          "quote": "Start simple. Add rules only when you notice the agent making the same mistake repeatedly.",
          "fragment": "Add rules only when you notice the agent making the same mistake repeatedly"
        },
        {
          "source": "cc-art-sdlc-playbook",
          "page": "The AI-native SDLC playbook",
          "url": "https://claude.com/resources/articles/the-ai-native-sdlc-playbook",
          "quote": "When Claude makes a mistake twice, the correction goes into CLAUDE.md.",
          "fragment": "the correction goes into CLAUDE.md"
        }
      ],
      "detect": "Instruction files show rule maintenance (recent edits, rules tied to observed failures, an eval or review loop); compare correction_categories counts. Judge from evidence; na if nothing can be seen.",
      "rule": {
        "text": "Semantic; na when nothing can be seen.",
        "params": {}
      },
      "fix_kind": "habit",
      "verifiedAt": "2026-11-11",
      "basis": "live",
      "consensus": {
        "verifiers": ["codex", "grok"],
        "agree": 2,
        "total": 2,
        "checkedAt": "2026-11-11"
      }
    },
    {
      "id": "doc-skills-on-demand",
      "dimension": "doc",
      "title": "Move workflow-specific instructions into on-demand skills",
      "title_zh": "流程类内容放 skill,按需加载",
      "sources": [
        {
          "source": "cc-costs",
          "page": "Claude Code costs",
          "url": "https://code.claude.com/docs/en/costs",
          "quote": "Skills load on-demand only when invoked, so moving specialized instructions into skills keeps your base context smaller.",
          "fragment": "load on-demand only when invoked"
        },
        {
          "source": "cc-costs",
          "page": "Claude Code costs",
          "url": "https://code.claude.com/docs/en/costs",
          "quote": "Aim to keep CLAUDE.md under 200 lines by including only essentials.",
          "fragment": "Aim to keep CLAUDE.md under 200 lines"
        }
      ],
      "detect": "Config: skill counts (active Claude roots, other_skills), CLAUDE.md lines; summary: concepts_pct.skill (context).",
      "rule": {
        "text": "Proxy: moving is not logged. Skills = Claude skills of active roots + ~/.codex/skills + ~/.agents/skills. part: a CLAUDE.md over 200 lines; ok: skills and every CLAUDE.md within 200 lines; na: neither skills nor a long CLAUDE.md.",
        "params": {
          "line_target": 200
        }
      },
      "fix_kind": "config",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "plan-mode-first",
      "dimension": "plan",
      "title": "Plan before coding on complex tasks",
      "title_zh": "复杂任务先规划再写代码(plan 模式)",
      "sources": [
        {
          "source": "cc-common-workflows",
          "page": "Claude Code common workflows",
          "url": "https://code.claude.com/docs/en/common-workflows",
          "quote": "Claude reads files and proposes a plan but makes no edits until you approve.",
          "fragment": "Claude reads files and proposes a plan but makes no edits until you approve"
        },
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "Plan mode lets Codex gather context, ask clarifying questions, and build a stronger plan before implementation.",
          "fragment": "Plan mode lets Codex gather context"
        },
        {
          "source": "cursor-agent-best-practices",
          "page": "Cursor agent best practices",
          "url": "https://cursor.com/blog/agent-best-practices",
          "quote": "The most impactful change you can make is planning before coding.",
          "fragment": "The most impactful change you can make is planning before coding"
        },
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "If the task is complex, ambiguous, or hard to describe well, ask Codex to plan before it starts coding.",
          "fragment": "ask Codex to plan before it starts coding"
        }
      ],
      "detect": "Summary: cohorts.complex (plan = plan mode; plan_or_sub adds a planning skill or ask-user before the first edit).",
      "rule": {
        "text": "Cohort (proxy for complex tasks): >=5 files edited or >=100 tool calls (>=10 per group). Claude (logs plan mode): ok: plan mode >=25%; part: plan or substitute >=10%; else no. Other hosts: substitutes >=25% ok, >=10% part, else na. Session-weighted (heuristic)",
        "params": {
          "complex_edited_files": 5,
          "complex_tool_calls": 100,
          "min_cohort": 10,
          "ok_pct": 25,
          "part_pct": 10
        }
      },
      "fix_kind": "habit",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "plan-interview",
      "dimension": "plan",
      "title": "Ask the agent to interview you when you don't know exactly what you want yet",
      "title_zh": "还没想清楚要什么时,让 agent 先访谈你",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "Ask Claude to interview you instead",
          "fragment": "Ask Claude to interview you instead"
        }
      ],
      "detect": "Summary: cohorts.complex.interview (ask-user or a grill/interview/brainstorm skill before the first edit).",
      "rule": {
        "text": "Option when you don't know what you want, which logs cannot see; complex sessions (>=5 files or >=100 tool calls) are the proxy. ok: interview in >=10%; below that na (no evidence either way); na: <10 in cohort (heuristic)",
        "params": {
          "min_cohort": 10,
          "ok_pct": 10
        }
      },
      "fix_kind": "habit",
      "verifiedAt": "2026-11-11",
      "basis": "live",
      "consensus": {
        "verifiers": ["codex", "grok"],
        "agree": 2,
        "total": 2,
        "checkedAt": "2026-11-11"
      }
    },
    {
      "id": "plan-done-when",
      "dimension": "plan",
      "title": "State the done criteria in the prompt",
      "title_zh": "提示里写明完成标准(Done when)",
      "sources": [
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "Done when: What should be true before the task is complete, such as tests passing, behavior changing, or a bug no longer reproducing?",
          "fragment": "What should be true before the task is complete"
        }
      ],
      "detect": "Usually na: needs semantic reading of prompts; pct_first_prompt_done_when is a keyword hint only.",
      "rule": {
        "text": "Semantic; usually na.",
        "params": {}
      },
      "fix_kind": "habit",
      "verifiedAt": "2026-11-11",
      "basis": "live",
      "consensus": {
        "verifiers": ["codex", "grok"],
        "agree": 2,
        "total": 2,
        "checkedAt": "2026-11-11"
      }
    },
    {
      "id": "verify-runnable-checks",
      "dimension": "verify",
      "title": "Have the agent run pass/fail checks, with the output as evidence",
      "title_zh": "让 agent 跑能判定通过与否的检查,并留下输出作证据",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "Give Claude something it can run that comes back pass or fail.",
          "fragment": "Give Claude something it can run that comes back pass or fail"
        },
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "ask Claude for evidence: the command it ran and its output, or the screenshot.",
          "fragment": "the command it ran and its output, or the screenshot"
        },
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "Ask it to create tests when needed, run the relevant checks, confirm the result, and review the work before you accept it.",
          "fragment": "Ask it to create tests when needed, run the relevant checks"
        },
        {
          "source": "cursor-agent-best-practices",
          "page": "Cursor agent best practices",
          "url": "https://cursor.com/blog/agent-best-practices",
          "quote": "Tests allow the agent to make changes, evaluate results, and incrementally improve until it succeeds.",
          "fragment": "Tests allow the agent to make changes"
        }
      ],
      "detect": "Summary: pct_coding_with_check, pct_session_bash_tags, correction_categories.not_verified.",
      "rule": {
        "text": "Coding = edits or commits; check = test/lint/typecheck at command position, or a screenshot; its command and output stay in the transcript as evidence (pass or fail is not judged). ok: >=50% of coding sessions; part: 20-49%; no: <20% (heuristic)",
        "params": {
          "ok_pct": 50,
          "part_pct": 20
        }
      },
      "fix_kind": "habit",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "verify-revert-retry",
      "dimension": "verify",
      "title": "When output is wrong, revert and rerun with a sharper plan instead of patching",
      "title_zh": "输出不对就回滚重来,不继续打补丁",
      "sources": [
        {
          "source": "cursor-agent-best-practices",
          "page": "Cursor agent best practices",
          "url": "https://cursor.com/blog/agent-best-practices",
          "quote": "Revert the changes, refine the plan to be more specific about what you need, and run it again.",
          "fragment": "Revert the changes, refine the plan"
        }
      ],
      "detect": "Usually na: reverts go through git, /rewind or manual edits; Grok signals.json hasReverted is a partial hint.",
      "rule": {
        "text": "na: no single log signal.",
        "params": {}
      },
      "fix_kind": "habit",
      "verifiedAt": "2026-11-11",
      "basis": "live",
      "consensus": {
        "verifiers": ["codex", "grok"],
        "agree": 2,
        "total": 2,
        "checkedAt": "2026-11-11"
      }
    },
    {
      "id": "auto-worktrees",
      "dimension": "auto",
      "title": "Give each parallel piece of work its own checkout (git worktree)",
      "title_zh": "并行工作各用独立 checkout(git worktree)",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "When you have separate pieces of work going at once, give each its own checkout so the edits can't collide.",
          "fragment": "give each its own checkout so the edits"
        },
        {
          "source": "codex-best-practices",
          "page": "Codex best practices",
          "url": "https://learn.chatgpt.com/guides/best-practices",
          "quote": "Running live tasks on the same files without using Git worktrees",
          "fragment": "Running live tasks on the same files without using Git worktrees"
        }
      ],
      "detect": "Summary: parallel (sessions, isolated, with_worktree, separate_clone): overlapping sessions that both edited files, grouped by git remote so clones of one repository meet; a worktree or another clone counts as isolated; cwd_top folds worktree dirs into their repo.",
      "rule": {
        "text": "Cohort: human sessions that edited files while another did in the same repo or a clone of it, overlapping >=5 min (sessions over 12 h ignored); same files not required. ok: worktree or separate clone in >=50%; part: some; no: none; na: <10 in cohort (heuristic)",
        "params": {
          "max_span_hours": 12,
          "min_cohort": 10,
          "ok_pct": 50,
          "min_overlap_minutes": 5
        }
      },
      "fix_kind": "habit",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "auto-headless",
      "dimension": "auto",
      "title": "Run Claude non-interactively for CI, hooks and batch jobs",
      "title_zh": "CI、git hook 和批处理用非交互(headless)模式跑",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "runs once and exits, which is how Claude Code ends up in CI jobs, git hooks, and shell loops.",
          "fragment": "runs once and exits"
        },
        {
          "source": "cc-common-workflows",
          "page": "Claude Code common workflows",
          "url": "https://code.claude.com/docs/en/common-workflows",
          "quote": "Run Claude non-interactively for CI, pre-commit hooks, or batch processing.",
          "fragment": "Run Claude non-interactively for CI"
        }
      ],
      "detect": "Summary: headless (sessions, self_audit, scheduled), human_repeated; config: schedulers.",
      "rule": {
        "text": "Headless = claude -p / codex exec / SDK sessions, own runs excluded. ok: any, or a scheduled headless job; else na (the pages describe use, not a duty). >=10 hand-typed sessions repeating a first-prompt shape >=3 times are listed as script candidates (heuristic)",
        "params": {
          "repeat_min": 3,
          "min_repeat_sessions": 10
        }
      },
      "fix_kind": "config",
      "verifiedAt": "2026-10-31",
      "basis": "live",
      "consensus": {
        "verifiers": ["claude (manual quote check)"],
        "agree": 1,
        "total": 1,
        "checkedAt": "2026-10-31"
      },
      "needs-consensus": true
    },
    {
      "id": "auto-headless-limits",
      "dimension": "auto",
      "title": "Give unattended runs a stop: --max-turns, --max-budget-usd or a spend limit",
      "title_zh": "无人值守运行设停止条件:轮数上限、花费上限或 spend limit",
      "sources": [
        {
          "source": "cc-best-practices",
          "page": "Claude Code best practices",
          "url": "https://code.claude.com/docs/en/best-practices",
          "quote": "What stops it? --max-turns, --max-budget-usd, a spend limit.",
          "fragment": "What stops it?"
        }
      ],
      "detect": "Config: schedulers and with_limits (--max-turns / --max-budget-usd in the job or its script). Spend limits are not visible locally.",
      "rule": {
        "text": "Unattended = scheduled headless jobs. na without them. ok: every job passes --max-turns or --max-budget-usd, or a spend limit the user names covers them; part: some; no: none.",
        "params": {}
      },
      "fix_kind": "config",
      "verifiedAt": "2026-11-11",
      "basis": "live",
      "consensus": {
        "verifiers": ["codex", "grok"],
        "agree": 2,
        "total": 2,
        "checkedAt": "2026-11-11"
      }
    },
    {
      "id": "ctx-compact-before-break",
      "dimension": "ctx",
      "title": "Compact before stepping away, while the prompt cache is warm",
      "title_zh": "离开前先 /compact,趁 prompt cache 还没过期",
      "sources": [
        {
          "source": "cc-art-maximizing-sessions",
          "page": "Maximizing the value of your Claude Code sessions",
          "url": "https://claude.com/resources/articles/maximizing-the-value-of-your-claude-code-sessions",
          "quote": "/compact before you take a break from your keyboard.",
          "fragment": "before you take a break from your keyboard"
        },
        {
          "source": "cc-art-maximizing-sessions",
          "page": "Maximizing the value of your Claude Code sessions",
          "url": "https://claude.com/resources/articles/maximizing-the-value-of-your-claude-code-sessions",
          "quote": "the cache expires after an hour on a subscription or five minutes on an API key",
          "fragment": "the cache expires after an hour"
        },
        {
          "source": "cc-art-opus-5-5-context",
          "page": "Coding sessions are longer and use more context. Claude Opus 5.5 is built with that in mind.",
          "url": "https://claude.com/resources/articles/claude-opus-5-5-built-for-coding-sessions-that-use-more-context",
          "quote": "Compact before you step away rather than after",
          "fragment": "Compact before you step away"
        }
      ],
      "detect": "Session logs (needs extract support): idle gaps inside one human Claude session (including a later --resume into the same transcript) of >=60 min between the last assistant entry and the next user prompt; whether a /compact or compaction boundary came right before the gap. Billing type is not logged, so the subscription hour is used.",
      "rule": {
        "text": "Gap = >=60 min idle inside a human Claude session before more work. ok: >=50% of gaps preceded by /compact; part: 10-49%; no: <10%; na: <10 gaps (heuristic)",
        "params": {
          "gap_minutes": 60,
          "ok_pct": 50,
          "part_pct": 10,
          "min_gaps": 10
        }
      },
      "fix_kind": "habit",
      "verifiedAt": "2026-11-11",
      "basis": "live",
      "consensus": {
        "verifiers": ["codex", "grok"],
        "agree": 2,
        "total": 2,
        "checkedAt": "2026-11-11"
      }
    }
  ],
  "pending": []
}
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall