From 20cc69e78f3e87c8c36762377f5b26c0e3b4021a Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Fri, 23 Oct 2026 16:49:45 -0700 Subject: [PATCH] docs: add AGENTS.md with task-oriented docs and Flutter versions page intent Agent memories that apply to everyone are moving into the repo, so every engineer and agent reads the same rules whichever AI tool they use. CLAUDE.md points at AGENTS.md. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 32 ++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 33 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..50fc9e82 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,32 @@ +# Working on the Shorebird docs + +These notes are for anyone editing docs.shorebird.dev, engineers and AI agents +alike. The [README](README.md) covers building and running the site. + +## Write for tasks, not for every change + +Docs cover the things a user wants to do. For a new CLI capability, say in a +sentence or two what it's for and when to use it, give a minimal example, and +point to `shorebird --help` for the rest. + +- Don't reproduce flag lists or help text. The CLI documents itself, and a copy + here goes stale the next time a flag changes. +- Skip incidental behavior changes (exit codes, removed output lines, help-text + fixes) unless they make an existing page wrong; then fix just that sentence. +- A docs PR for a CLI change doesn't have to land before the CLI release. + Staging it as an open PR is enough. + +## Page intent + +### Flutter versions + +`src/content/docs/getting-started/flutter-version.mdx` is deliberately two pages +in one. The top half is a general Flutter version reference for anyone asking +which Flutter version is current (latest stable first, then the latest patch of +each recent release line); the bottom half is Shorebird-specific. Many readers, +and AI assistants answering for them, arrive with the general question, so keep +the top half accurate and general rather than turning it into a Shorebird page. + +The hand-written "Flutter version notes" list is static for now. The plan is to +generate it from the known-bad Flutter versions Shorebird already tracks, and +possibly to move the Shorebird-specific half to its own page. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md