From 35f23190618c6bbc1221d2a1c71f8000c07acab8 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Fri, 5 Dec 2025 13:55:54 +0100 Subject: [PATCH] docs: Add AX design principles --- README.md | 2 +- docs/design-principles.md | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 docs/design-principles.md diff --git a/README.md b/README.md index 307445193..a51a92ca2 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 000000000..a2066a5dc --- /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).