Consolidated from ADR-0011, ADR-0012, ADR-0021, and ADR-0026 on 2026-05-02 per ADR-0047. Source files retained with deprecation banners at
docs/adr/0011-claude-code-iac-authoring.md,docs/adr/0012-wsl-ubuntu-alienware-dev-env.md,docs/adr/0021-claude-code-developer-tooling.md, anddocs/adr/0026-claude-code-optimization-mcp.md.
DEV-0001 — Developer Environment: Claude Code, WSL CanEast AI Node, MCP Strategy¶
| Field | Value |
|---|---|
| Status | Accepted |
| Date | 2026-04-06 (latest source) |
| Author | Ben Peries |
| Sources | ADR-0011 (Claude Code IaC), ADR-0012 (WSL dev env), ADR-0021 (Claude Code tooling), ADR-0026 (optimization and MCP) |
Context¶
The Archon Platform spans Ansible, Terraform, k3s, Azure DevOps pipelines, OT firmware, and documentation — operated by a single engineer. Three related decisions were established across separate ADRs:
-
Development workstation (ADR-0012): The CanEast AI Node (REDACTED) running WSL on Windows is the primary development environment. It provides native Linux tooling and GPU passthrough for AI workloads without dual-boot overhead.
-
Primary IaC authoring tool (ADR-0011, ADR-0021): Breadth of platform work exceeds what one person can efficiently author manually. Local models (Ollama, Qwen3:4b) handle quick lookups but lack the context window and reasoning depth for multi-file infrastructure tasks. Claude Code was adopted as the primary AI developer assistant.
-
Operational optimization (ADR-0026): After several weeks of use, token costs reached ~$65/day running pure Opus 4.6. A cost optimization strategy was needed without sacrificing capability, alongside a standardized way to give Claude Code context across all repos and connect it to external services via MCP.
Decision¶
Development workstation — WSL on CanEast AI Node (from ADR-0012)¶
WSL on the CanEast AI Node is the primary development environment for all Archon platform work.
- OS: Ubuntu (WSL) on Windows
- GPU: REDACTED — passed through to WSL for Ollama/CUDA
- Claude Code: runs in WSL terminal at
~/homelab/repos/ - Ollama: Docker container with GPU access, exposed on
REDACTED:11434 - Open WebUI:
REDACTED:3000 - SSH to nodes: via
~/.ssh/configwith ansible-svc-account key, port REDACTED
Why WSL, not native Linux: WSL provides native Linux tooling (Ansible, Terraform, git, az cli) without dual-boot overhead. GPU passthrough enables local AI inference (Qwen3:4b runs 100% on REDACTED). Windows host handles driver stability and desktop applications.
All IaC development happens in WSL — nodes are deployment targets only. WSL networking
uses NAT; REDACTED is the Windows host IP visible on LAN.
Alternatives rejected: - Native Linux on CanEast AI Node — better performance, but loses Windows desktop and GPU driver stability - Develop directly on caneast-site1-node3 — limited RAM (8GB), no GPU - Cloud dev environment — latency, cost, and internet dependency for homelab work
Primary IaC authoring tool — Claude Code (from ADR-0011, ADR-0021)¶
Claude Code (Anthropic CLI, claude-sonnet-4-6) is the primary AI developer assistant
for all Archon platform work.
- Installed on: CanEast AI Node — WSL
- Working directory:
~/homelab/repos/ - Model: Claude Sonnet 4.6
- Scope: Ansible role authoring/auditing, Terraform modules, k3s manifests, ADR writing, PR creation, Azure DevOps CLI operations, ansible-lint triage, documentation
Boundary with local AI stack¶
| Use case | Tool |
|---|---|
| Quick lookups, chat, exploratory questions | Ollama / Open WebUI (Qwen3:4b) |
| IaC authoring — Ansible, Terraform, k3s manifests | Claude Code |
| ADR writing, PR descriptions, doc updates | Claude Code |
| Azure DevOps CLI operations from terminal | Claude Code |
| OT firmware (ESP32, Arduino) | Claude Code or Ollama (TBD) |
Alternatives rejected: - Ollama (Qwen3:4b) for all tasks — insufficient context window for multi-file audits - GitHub Copilot — IDE-only, no terminal/CLI integration, weak for IaC - No AI tooling — single operator with broad scope; AI assistance materially reduces time-to-deploy
Constraints:
- PATs and sensitive credentials must not be typed into the Claude Code prompt — use env vars
and credential helpers
- Session context is not persistent across restarts — .claude/ memory directory used for
cross-session context
- Claude Code does not have network access to internal services — all runs executed locally
Operational optimization — model config, CLAUDE.md, MCP (from ADR-0026)¶
Model configuration (~/.claude/settings.json)¶
| Setting | Value | Rationale |
|---|---|---|
| Default model | claude-sonnet-4-6 | Best quality/cost ratio for IaC tasks |
| Subagents | claude-haiku-4-5 | Lightweight tasks, file reads, searches |
| Thinking budget | 10,000 tokens | Sufficient for architecture decisions |
| Auto-compact | 50% threshold | Prevents context overflow on long sessions |
| Statusline | cost display enabled | Real-time spend visibility |
Projected cost: under $15/day vs $65/day pure Opus — approximately 75% reduction.
Context portability — CLAUDE.md¶
All 6 repos have a CLAUDE.md at root that:
1. Points to archon-docs/docs/_context.md as the primary AI context source
2. Declares repo-specific scope and constraints
3. Is the first file Claude Code reads on session start
Global ~/.claude/CLAUDE.md provides baseline identity and platform context.
No Memory MCP needed — generate-context.py auto-refreshes _context.md on every push
to archon-docs main.
MCP servers¶
| Server | Package | Scope | Auth |
|---|---|---|---|
| Azure DevOps | @tiberriver256/mcp-server-azure-devops | archon-platform repo (.mcp.json) |
PAT (project-scoped) |
| Azure Infrastructure | @azure/mcp | Global (~/.claude/) |
Azure CLI credentials |
ADO MCP config lives in archon-platform/.mcp.json — not global, scoped to platform IaC work.
Microsoft official ADO MCP OAuth not yet supported in Claude Code as of April 2026 — PAT used
as interim solution.
Why MCP: MCP servers are the programmatic layer that makes AI portability real. Any model
connecting to these MCPs gets live platform state — current cluster status, pipeline runs,
secrets metadata, DNS config — not stale context from a previous session. MCP is the runtime
expression of the AI portability principle; ADRs and _context.md are the static expression.
Usage tracking¶
- ccusage CLI installed — token and cost reporting
- Daily cron at 23:[REDACTED] exports
claude-usage-30d.jsonto~/homelab/data/claude-usage/ - Planned: Node-RED → InfluxDB → Grafana dashboard for cost visualization
settings.local.json hygiene¶
archon-platform/.claude/settings.local.json: trimmed to 25 generic permission entries~/homelab/.claude/settings.local.json: trimmed to 16 entries- Keep only generic tool permission grants; no hardcoded credentials, PR-specific one-liners, or repo-specific paths
Consequences¶
- WSL on CanEast AI Node is the primary development environment; nodes are deployment targets only
- Claude Code (claude-sonnet-4-6) is the primary IaC authoring tool; Ollama handles quick lookups
- Sonnet 4.6 default / Haiku 4.5 subagents / 10K thinking / 50% auto-compact delivers ~75% cost reduction over pure Opus
- CLAUDE.md must be kept current when platform state changes significantly
- PAT for ADO MCP must be rotated per standard rotation runbook
- Cloudflare MCP identified as next MCP addition — replaces curl one-liners for DNS/Pages/Workers
- DEV-0002 (CanEast AI Node workstation-as-code) builds on this foundation; all config in
config/claude/under archon-platform
References¶
- DEV-0002 — CanEast AI Node workstation-as-code (Ansible role, config/claude/, bootstrap script)
- DEV-0003 — Workstation Secret Zero (Infisical bootstrap credential)
- IAM-0001 — Infisical for secrets (credential handling for AI tooling)
- IAM-0003 — Ansible service account (ansible-svc-account pattern applied to MCP auth)
docs/reference/ai-portability.md— AI portability philosophy- CanEast AI Node: REDACTED, WSL,
~/homelab/repos/