diff --git a/docs/agent-dx-log.md b/docs/agent-dx-log.md index 5f6c017..406da46 100644 --- a/docs/agent-dx-log.md +++ b/docs/agent-dx-log.md @@ -3,6 +3,30 @@ How measurements from [honojs/agent-dx](https://github.com/honojs/agent-dx) changed Hono CLI. Newest first. +## 2026-09-06: An executable spec wins — when the user hands it over + +**Experiment**: the auto-mode task re-run with `expect` (`next.4`), +haiku, 3 runs per condition. + +**Findings**: + +- The agent writing `checks.jsonl` from the spec table itself: 2/3, + 110k — transcription mixes interpretation in. +- A ready-made `checks.jsonl` shipped with the task: 3/3, median 65k + tokens, 43s — the top of every condition measured so far, beating + hand-written scripts (3/3, 92k, 92s). Every run opened with + `--batch checks.jsonl`, implemented, and finished at `failed: 0`. +- So `expect` pays off with a workflow: the user (or an approved + draft) hands the agent an executable acceptance spec. +- Also recorded: a real Claude Code run tried `npx hono dev &` — it + expects a dev server to exist. + +**Changes**: `dev` / `serve` / `start` now answer with the point of +the whole design: "No server needed. Send requests directly: +hono request /path". Open ideas, not yet built: scaffolding +`checks.jsonl` from the routes, and a docs section on handing specs +to agents. + ## 2026-09-05: `expect` returns — measurement beats our reasoning **Experiment**: an auto-mode task (build a shop API against an diff --git a/src/utils/output.test.ts b/src/utils/output.test.ts index 5ce8675..e0058b7 100644 --- a/src/utils/output.test.ts +++ b/src/utils/output.test.ts @@ -55,6 +55,13 @@ describe('formatArgumentsError flag fixes', () => { ]) }) + it('should point an invented server command at request', () => { + const parsed = JSON.parse(formatArgumentsError("error: unknown command 'dev'")) + expect(parsed.error.suggestions).toEqual([ + 'No server needed. Send requests directly: hono request /path', + ]) + }) + it('should map an invented flag to the real one', () => { const body = JSON.parse(formatArgumentsError("error: unknown option '--body'")) expect(body.error.suggestions[0]).toContain('-d') diff --git a/src/utils/output.ts b/src/utils/output.ts index 4a96a36..39685fc 100644 --- a/src/utils/output.ts +++ b/src/utils/output.ts @@ -47,10 +47,19 @@ const FLAG_FIXES: Record = { '-m': 'The method flag is -X: hono request /api/users -X POST', } +// There is no server command on purpose. Agents that expect one get +// pointed at the serverless flow. +const COMMAND_FIXES: Record = { + dev: 'No server needed. Send requests directly: hono request /path', + serve: 'No server needed. Send requests directly: hono request /path', + start: 'No server needed. Send requests directly: hono request /path', +} + export const formatArgumentsError = (message: string): string => { const cleaned = message.replace(/^error: /, '').trim() const flag = cleaned.match(/unknown option '([^']+)'/)?.[1] - const fix = flag ? FLAG_FIXES[flag] : undefined + const command = cleaned.match(/unknown command '([^']+)'/)?.[1] + const fix = (flag && FLAG_FIXES[flag]) || (command && COMMAND_FIXES[command]) || undefined const suggestions = [fix ?? 'Check the usage: hono --help'] return formatError(new CliError('INVALID_ARGUMENTS', cleaned, { suggestions })) }