📚 Documentation: Should agent documentation explicitly warn about the --port ...

Date: 2026-02-06
Time: 21:17:01 UTC
Session: editor2-97.13
Agent: documentation
Confidence: 100%
Status: ✅ Documented

📋 Decision Context

Question:

Should agent documentation explicitly warn about the --port / inspector port conflict for backends?

Task: Update AGENTS.md and CLAUDE.md with --port safety rules

🎯 Decision Made

Chosen:

Document in both AGENTS.md and CLAUDE.md with examples

Options Considered:

1. Leave it undocumented and rely on dev-serve.js safety net
2. Document in AGENTS.md only
3. Document in both AGENTS.md and CLAUDE.md with examples

💭 Reasoning

dev-serve.js strips --port for backends as a safety net, but agents can still bypass it with direct npx nx serve calls. Both AGENTS.md and CLAUDE.md are read by every agent session. Added: (1) A CRITICAL section under Port Rules explaining --port means inspector for @nx/js:node, (2) An explicit table showing frontend vs backend --port behavior, (3) Updated the 'Switching to gspace1' section to show ❌ for backend --port usage, (4) Added WebSocket 400 and EADDRINUSE to the Quick Fixes table, (5) Added the rule to NX Build Rules table. Belt-and-suspenders: code safety net + documentation + MCP decision history.

📁 Files Involved

• AGENTS.md
• CLAUDE.md

🔗 Related

• Decision ID: dev_1770412621367_rciw9pt
• Session: 97
• Workspace: editor2

Auto-generated by MCP Smart Consolidation