Adonis0123/adonis-skills / skills/agent-practice-audit
agent-practice-audit
FlaggedScore 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.
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": []
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |