claude-guidelines

name

claude-guidelines

description

Encodes the mandatory personal development workflow for all Claude interactions: MCP router discovery policy, LOI-first codebase navigation, TDD testing, domain/app/infrastructure architecture, Git branch-PR workflow, fetch-mcp for all HTTP/search, and JSON optimization. This skill should be active for every software engineering task — coding, searching, fetching URLs, writing tests, designing architecture, or navigating a codebase. Invoke it whenever working on any code task, especially when using MCP tools, searching the web, fetching URLs, navigating a codebase, writing tests, or planning git commits.

MCP Tool + Skill Policy

Before using any external capability, always discover it first via the router:

1. Call discover_skill for any task that produces a file or needs specialist knowledge.
2. Call load_skill to load the skill's full instructions before executing.
3. Call discover_tools before any task needing external capabilities (web, databases, APIs, git hosting, files outside the project).
4. Call activate_server for every server discover_tools returns before calling its tools.
5. Never assume a tool or skill exists from a prior session — always discover first.
6. Never call tools from servers not listed in list_active_servers.

Why: The router keeps the context window lean. Bypassing it front-loads all schemas and defeats the purpose.

Scope: Applies to MCP-provided capabilities and registered skills only. Native Claude Code tools (Read, Write, Edit, Bash, Grep, Glob) don't need discovery.

Correct flow:

User: "search github for open bugs"
✓ discover_tools("search github issues")  → finds github server
✓ activate_server("github")               → loads github tools
✓ search_issues(label: "bug")             → executes task

User: "create a word document"
✓ discover_skill("create a word document") → finds docx skill
✓ load_skill("docx")                       → loads instructions
✓ execute task using loaded skill

---

Design

Always use the frontend-design skill for any UI or frontend work — components, pages, applications, layouts.

---

Codebase Search

Never start with Grep or Glob. Use LOI navigation first.

LOI + codedetect (Mandatory First Step)

1. Check for LOI index: Read <cwd>/docs/index/_root.md. If not found, use rg --files --glob '**/docs/index/_root.md' via Bash.
2. If it exists: Call load_skill("loi"), then navigate Campus → Building → Room. Do not skip to Grep.
3. Use codedetect Plugin for structured code detection in parallel with LOI when both apply.
4. Only after LOI, if you still need a specific symbol or line, use Grep/Glob for targeted follow-up.

Parallelism: Invoke LOI and codedetect in parallel when both are relevant — don't serialize them.

File & Content Search

• File search: Glob tool (not fd, not find)
• Content search: Grep tool (not rg, not grep)
• Exception: LOI index discovery must use rg --files via Bash — Glob times out on broad ** patterns from parent directories.

---

Development Workflow

Write or update the LOI intent before any implementation code. The index is the contract; the code fulfills it.

1. New project or major change: Call load_skill("loi-generate") (Full-Generate mode).
2. Incremental work: Manually add/update the relevant Room entry in docs/index/ before writing code, then call load_skill("loi-generate") (Incremental-Generate mode) to refresh.
3. After implementation: If code diverged from intent, update the LOI entry to match reality (/loi update).

---

Architecture

Separate code into three clear layers:

• Domain — pure business logic and entities; no framework or infrastructure dependencies.
• Application — orchestrates domain logic, handles use cases, coordinates side effects.
• Infrastructure — databases, HTTP clients, message queues, external APIs — all at the edges.

Ports and adapters: Only introduce an interface/port when there is a real, near-term reason to swap the implementation. No speculative ports.

Default to boring: Start with the simplest structure that correctly separates concerns. Add abstraction only when the complexity earns it.

---

Testing

Follow TDD for all code changes:

1. Write a failing test that defines the expected behavior.
2. Write the minimum code to make it pass.
3. Refactor without breaking the test.
4. Run the full test suite before every commit. Never commit with failing tests.

---

Git Workflow

For any non-trivial change:

1. Branch first: Create a feature branch. Never work directly on main/master.
2. Commit often: Small, focused commits — don't batch everything.
3. Open a PR: Clear title and summary.
4. Wait for checks: Monitor CI; do not proceed until all pass.
5. Address feedback: Fix each review comment and resolve the thread with a short explanation.
6. Iterate until green: Repeat steps 4–5 until all checks pass and feedback is resolved.

---

Web Search & HTTP Fetching

Use fetch-mcp for everything HTTP-related. Never use curl, wget, http, httpie, or other shell-based HTTP clients.

Need	Tool
General URL fetch (HTML or JSON)	smart_fetch
Targeted DOM extraction	css_query
JavaScript-rendered pages	browser_fetch
Web search	web_search
Post-processing large JSON	optimize_json

Only fall back to shell HTTP tools if fetch-mcp lacks the capability (e.g., binary file upload, custom auth flow) — briefly note why before doing so.

---

JSON Optimization

When any MCP tool returns a JSON response larger than ~50 lines, pass it through optimize_json from fetch-mcp before reasoning over it. You can pass raw JSON or a file path directly. Use jsonpath to drill into specifics rather than consuming the full payload.