Update best practices for Dev Proxy v2.2.0

[garrytrinder]

Updates the best practices document with new features and guidance from Dev Proxy v2.2.0:

• YAML config support — added .yaml/.yml as supported config formats alongside JSON
• devproxy config validate — new subcommand for pre-run config validation
• devproxy config new --format yaml — creating YAML configs
• @dynamic=initialvalue — per-response retry-after with initial values in GenericRandomErrorPlugin
• --no-watch flag — disable hot reload for CI/CD and automation
• Detached mode — background execution for pipelines and agent workflows
• --output json|text — structured output for automation

[waldekmastykarz]

Let's add info about random ports which is invaluable for detached mode, especially combined with asSystemProxy false

[garrytrinder]

Let's add info about random ports which is invaluable for detached mode, especially combined with asSystemProxy false

@copilot

[Copilot]

@garrytrinder I've opened a new pull request, #114, to work on those changes. Once the pull request is ready, I'll request review from you.

[garrytrinder]

Best Practices Document Review — Report

Context

The best-practices.md file is served to coding agents (LLMs) as additional context via the Dev Proxy MCP server. Its purpose is to instruct agents on how to correctly configure and use Dev Proxy. This review was prompted by the Dev Proxy v2.2.0 release and an opportunity to assess whether the document format was fit for purpose.

Summary of changes

1. New content for Dev Proxy v2.2.0

Added rules covering new v2.2.0 features:

• YAML config support — devproxyrc.yaml/devproxyrc.yml as config formats, devproxy config new --format yaml
• Config validation — devproxy config validate subcommand
• @dynamic=initialvalue — per-response Retry-After with initial values in GenericRandomErrorPlugin
• --no-watch flag — disable config auto-reload
• Detached mode — background execution with --output json, random ports (port: 0), and asSystemProxy: false

2. Tone: directive, not suggestive

Problem: The original document used hedging language — "consider using", "prefer specifying", "you could" — which is appropriate for human documentation but ambiguous for an LLM. An agent has no judgment to apply to "consider"; it needs a clear instruction.

Change: Every rule is now a direct instruction. "Consider using the LatencyPlugin" became "When mocking APIs, use the LatencyPlugin." Where exceptions exist, they're stated explicitly: "Store files in .devproxy/, unless the project already has Dev Proxy files elsewhere."

Reasoning: LLMs follow instructions more reliably when they are unambiguous. Hedging language creates unpredictable agent behavior — sometimes following the suggestion, sometimes not, with no consistent rationale.

3. Severity: everything is mandatory with explicit exceptions

Problem: An initial pass introduced MUST/SHOULD/MAY severity levels (RFC 2119 style). However, SHOULD is ambiguous for an agent — it has no criteria to decide when to follow a recommendation and when to skip it.

Change: Dropped SHOULD and MAY entirely. Every rule is mandatory (stated once in the header). Where a rule has exceptions, the exception is explicit and conditional: "unless the user explicitly requests YAML", "unless a specific port is required."

Reasoning: An agent needs deterministic rules. "SHOULD do X" gives no decision criteria. "Do X, unless Y" gives a clear rule with a clear escape hatch.

4. Format: flat numbered list with domain tags

Problem: The original used markdown headings with per-section numbered lists. This created several issues for LLM consumption:

• Small sections (1-2 rules) added heading overhead for minimal content
• Numbered lists reset per section, making rules ambiguous to reference ("rule 1" in which section?)
• Headings create artificial separation between related rules

Change: Replaced headings + per-section lists with a single continuously numbered list (1-34). Each rule is tagged with a domain: [config], [urls], [plugins], [mock], [cli].

Reasoning:

• Continuous numbering — every rule is uniquely addressable (rule 24 is always "most specific URLs first in mocks")
• Domain tags — provide the same grouping benefit as headings but without structural overhead
• Token efficiency — fewer markdown tokens spent on headings, blank lines, and section scaffolding
• Linear reading — LLMs process context linearly; a flat list matches how the model actually reads the content

5. Removed fluff and redundancy

Problem: The original contained explanatory prose ("Hot reload helps you iterate faster", "This allows you to define the URLs in one place and have them applied globally") and repeated rationale across sections. Motivational or explanatory text doesn't help an agent act — it just consumes tokens.

Change: Stripped all explanatory prose. Each rule states what to do and, where relevant, when to do it. Nothing more.

Reasoning: Every token in the context window matters. Explanatory text competes with actionable instructions for the model's attention. Removing it makes the rules denser and more likely to be followed.

6. Conditions front-loaded

Problem: Version conditions were buried in parentheses: "use devproxy config new --format yaml (v2.2.0+)". An LLM can miss parenthetical conditions.

Change: Conditions are now at the start of rules: "When version >= 2.2.0, run devproxy config validate..."

Reasoning: Front-loading conditions makes them harder to skip. The agent evaluates the condition before reading the instruction, reducing the chance of applying a v2.2.0 rule to an older version.

Before/after comparison

Aspect	Before	After
Format	Headings + per-section bullet/numbered lists	Flat numbered list (1-34) with domain tags
Sections	7 headings (some with 1-2 items)	0 headings, 5 domain tags
Tone	Suggestive ("consider", "prefer")	Directive ("use", "put", "define")
Severity	Implicit	All mandatory, exceptions explicit
Version conditions	Parenthetical — "(v2.2.0+)"	Front-loaded — "When version >= 2.2.0:"
Fluff	Explanatory prose, motivational text	None
v2.2.0 coverage	None	YAML config, validation, detached mode, random ports, --no-watch, @dynamic=initialvalue

[waldekmastykarz]

Not sure how widely used, but this could interfere with custom plugins for which we don't have docs. Might be good to test if the agent understands the difference.