AI 原生开放教材

外观

Better Harness（QoderAI）工程手册·英文原文 ↗原件 ↓仓库 ↗

Route Better Harness recommendations by user support stage ​

Traceability ​

Intent ​

Keep Better Harness scoring and finding eligibility evidence-bound while adapting the final recommendation style to the user's next operating stage. Add three flat, conditionally loaded Skill references for Bootstrap, Operationalize, and Optimize guidance. Keep the root Skill responsible only for selecting one track after findings and dimension scores are frozen.

Treat 0 -> 1, 1 -> 60, and 60 -> 100 as user-journey labels, not score bands. A high or low score alone must never select a track.

Acceptance Scenarios ​

  • BHST-AC-1: skills/better-harness/SKILL.md selects exactly one primary support track after findings and dimension scores are frozen, or reports the track as undetermined when required evidence is unavailable.
  • BHST-AC-2: Bootstrap guidance combines authorized project facts, Agent Customize evidence, and user configuration to propose the smallest useful AGENTS.md, Rules, validation, or risk-boundary artifact without inventing commands or gaining mutation authority.
  • BHST-AC-3: Operationalize guidance converts supported present-but-not-wired or wired-but-not-exercised gaps into observable priority moves, concrete durable owners, and verification or recovery boundaries.
  • BHST-AC-4: Optimize guidance requires comparable Session Episodes before recommending workflow or asset changes, prefers built-in and existing owners before extension or creation, and requires later outcomes before claiming effectiveness.
  • BHST-AC-5: The three references stay flat and link directly from SKILL.md. Only the selected reference is loaded; no new score, finding, report field, specialist lane, delegated agent, or runtime command is introduced.
  • BHST-AC-6: Each track links to a repository case study that calibrates its advice, and focused tests verify routing, evidence gates, file budgets, and Markdown link integrity.

Non-goals ​

  • Recalibrating Agent Work Loop scores or interpreting score ranges as maturity.
  • Treating missing AGENTS.md, Rules, Skills, Hooks, Memory, or Session evidence as a finding by itself.
  • Generating or mutating project assets during read-only Better Harness analysis.
  • Adding a support-track field to findings.json or changing renderer schemas.
  • Duplicating the detailed Session, Project Harness, Agent Customize, finding, repair, or Loop Discovery contracts inside the new references.

Plan and Tasks ​

  1. Add three compact flat references with track-specific evidence and output rules, routing each to existing canonical owners and case studies.
  2. Add a compact post-score selection gate to the root Skill and keep all final finding, authorization, and report boundaries unchanged.
  3. Extend the focused Better Harness Skill test and generated Markdown routing graph for the new one-hop references.
  4. Run Skill validation, focused tests, link checks, package verification, and example-driven forward tests; iterate on any ambiguous route.

Test and Review Evidence ​

  • BHST-AC-1..AC-5: node --test test/better-harness-skill.test.mjs.
  • BHST-AC-5..AC-6: node scripts/doc-link-graph/cli.mjs skills/better-harness and node --test test/doc-link-graph.test.mjs.
  • Skill structure: Skill Creator quick_validate.py against skills/better-harness.
  • Package surface: npm run pack:verify.
  • Example behavior: read-only forward tests using the Agent Customize AGENTS.md fragments, Project Harness artifact catalog, and existing bug-diagnosis Skill case studies.

Verification Evidence ​

  • Skill Creator quick_validate.py passed for skills/better-harness.
  • node --test test/better-harness-skill.test.mjs passed 10 of 10 tests.
  • The regenerated Better Harness link graph contains 34 files and 50 links; node --test test/doc-link-graph.test.mjs passed 5 of 5 tests.
  • npm run pack:verify passed with an isolated writable npm cache: 288 npm package entries and 322 runtime zip entries.
  • npm test passed 816 of 819 tests in the sandbox. The only failures were the three unchanged preview-server cases blocked by listen EPERM 127.0.0.1; node --test test/preview-servers.test.mjs then passed 8 of 8 in a loopback-capable environment.
  • The three support references match the Hyperdrive source commit byte for byte. That source passed fresh read-only Bootstrap, Operationalize, and Optimize example forward tests without inventing evidence, expanding mutation authority, or creating a duplicate Skill when existing coverage matched the demand.