Skip to content

Chrome DevTools for coding agents

docs: Add AX design principles (#643)

Michael Hablich90ed192c558d
diff --git a/README.md b/README.md
index 30744519..a51a92ca 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ control and inspect a live Chrome browser. It acts as a Model-Context-Protocol
(MCP) server, giving your AI coding assistant access to the full power of
Chrome DevTools for reliable automation, in-depth debugging, and performance analysis.
-## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md)
+## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)
## Key features
diff --git a/docs/design-principles.md b/docs/design-principles.md
new file mode 100644
index 00000000..a2066a5d
--- /dev/null
+++ b/docs/design-principles.md
@@ -0,0 +1,10 @@
+# Design Principles
+
+These are rough guidelines to follow when shipping features for the MCP server.
+Apply them with nuance.
+
+- **Agent-Agnostic API**: Use standards like MCP. Don't lock in to one LLM. Interoperability is key.
+- **Token-Optimized**: Return semantic summaries. "LCP was 3.2s" is better than 50k lines of JSON. Files are the right location for large amounts of data.
+- **Small, Deterministic Blocks**: Give agents composable tools (Click, Screenshot), not magic buttons.
+- **Self-Healing Errors**: Return actionable errors that include context and potential fixes.
+- **Human-Agent Collaboration**: Output must be readable by machines (structured) AND humans (summaries).