Article Review: Group 8 — AI + Architecture Role¶

Articles Reviewed¶

Best Practices for Maximizing Claude Code Performance — Terry Cho — Practical tips: CLAUDE.md, slash commands, workflows, multi-Claude patterns
A Senior Engineer's Concern That Revealed the Most Important Role in Tech — Han HELOIR — Three categories of agentic work, five agentic levels, architect's role in AI era
Can AI Replace Software Architects? — CloudWay Digital — Tested 4 LLMs on crypto exchange architecture, rated outputs

Key Concepts¶

Claude Code Best Practices (Cho)¶

Explore → Plan → Code → Commit workflow: Break tasks into progressive steps instead of giving one large instruction. Matches our "architecture first" rule.

TDD with AI: Write tests first, confirm they fail, then have Claude implement. Clear measurable goals produce better results.

Multi-Claude patterns: - Writer/Reviewer in parallel terminals - Git worktrees for parallel feature/bugfix work

Key reader comment (Tangi Vass): "Don't use CLAUDE.md to describe your repo in great details, Claude would figure this out easily. Rather make it a legal document framing what is forbidden, what are the recommended alternatives, the different collaboration modes."

This validates our rules-based CLAUDE.md approach — our rules/ directory IS the "legal document" of constraints.

Three Categories of Agentic Work (Han HELOIR)¶

Category	Structure	Production Value	Our Mapping
1. Deterministic Workflows	Predefined flow, LLM adds intelligence within steps	80%+ of production value	Our NGE pipeline: ProcessorApi → extractor → loader → uploader. Steps are known; each adds domain logic.
2. Autonomous Agents	Structure unknown until runtime	Expensive, non-deterministic	Claude Code sessions exploring unfamiliar code
3. Hybrid	Workflow shell + agent core	Most mature production systems	Our Claude Code + skills + rules: workflow (skills) constrains the outer loop, Claude decides within each step

Five agentic levels (most value at 2-3, not 5): 1. Single LLM call 2. Augmented LLM (tools + memory) — most "AI assistants" 3. Workflows (orchestrated LLM calls) — where revenue lives 4. Bounded agents (LLM directs within constraints) 5. Autonomous agents (minimal oversight)

"Least agency" principle: Use the minimum agentic level needed. Don't build Level 5 when Level 3 solves the problem.

Key thesis: "The bottleneck has shifted from model capability to everything around the model — strategy, data readiness, architectural decisions, evaluation frameworks, security posture."

LLM Architecture Test Results (CloudWay)¶

Tested GPT-4o, Claude 3.7 Sonnet, Gemini 2.0 Flash, Grok 3 on designing a crypto exchange:

All LLMs produced "consulting-grade first drafts" but: - Generic, full of implicit assumptions - No trade-off analysis or justification for choices - No phased implementation thinking - Buzzwords without reasoning (suggested CQRS without explaining why) - No architectural storytelling

Self-ratings: 5-7/10 when asked to review their own output. Every LLM identified gaps in its own design.

Conclusion: LLMs are excellent research assistants and first-draft generators, but cannot replace the architect's judgment on trade-offs, sequencing, and context-specific decisions. The architect's value is in the WHY, not the WHAT.

Mapping to Our Architecture Repo & Claude Code Config¶

What We Do Right¶

CLAUDE.md as constraint document — Our CLAUDE.md focuses on rules, patterns, and conventions — not repo description. This matches the "legal document" advice from Cho's article.
Rules enforce architectural decisions — Our 7 rules files encode the "why" that LLMs miss: why core/ can't import shell/ (hexagonal boundaries), why events must be past-tense (domain events as facts), why exceptions route differently (exception hierarchy controls SQS behavior).
Reference-before-generate pattern — Our Rule 2 in ai-assisted-development.md says "search patterns/ and reference-implementations/ first." This prevents the generic, assumption-filled output the CloudWay article found.
Category 1 architecture — Our NGE pipeline is a deterministic workflow where each module adds domain intelligence within predefined steps. This is where 80%+ of production value lives, per Han HELOIR.

Improvements Identified¶

1. HIGH: Add "Least Agency" Principle to ai-assisted-development.md¶

Han HELOIR's "least agency" principle should be codified: use the simplest approach that works.

Add to ai-assisted-development.md:

## Rule 8: Least Agency
Use the simplest approach that solves the problem:
- Single prompt > multi-step workflow
- Specific file read > broad codebase search
- Pattern reference > generating from scratch
- Slash command > freeform instruction
- Agent tool only when exploration scope is genuinely unknown

Don't use sub-agents when a grep will do.
Don't use Plan mode when the task is a one-file change.

2. MEDIUM: Add Architect's Role Framing¶

The CloudWay article proves LLMs produce generic architecture without trade-off reasoning. Our rules should explicitly frame the architect's role in AI-assisted development:

The architect provides: - WHY a pattern was chosen (ADRs capture this) - WHAT trade-offs were accepted (ADR Consequences section) - WHEN to deviate from patterns (hot spots from EventStorming) - HOW modules interact (event catalog, divergence map)

The AI provides: - Code generation within established patterns - Exploration and analysis of unfamiliar code - Consistency checking against rules - Boilerplate and scaffolding

3. LOW: Add Explore → Plan → Code → Commit to CLAUDE.md¶

Cho's workflow is a practical version of our "architecture first" rule. Adding it as a recommended workflow pattern in CLAUDE.md session hygiene would help new users of the repo.

Actionable Changes¶

Change	Target	Priority
Add Rule 8 "Least Agency" to ai-assisted-development.md	`rules/ai-assisted-development.md`	HIGH
Add architect/AI role framing to ai-assisted-development.md	`rules/ai-assisted-development.md`	MEDIUM
Add Explore→Plan→Code→Commit workflow to CLAUDE.md session hygiene	`CLAUDE.md`	LOW

Summary¶

The three articles converge on a single theme: architecture is more valuable in the AI era, not less. LLMs produce generic first drafts (CloudWay test), but the architect provides trade-off reasoning, constraint encoding, and phased implementation thinking. Our architecture repo is already structured to support this — rules encode constraints, patterns provide references, ADRs capture decisions. The key addition is the "least agency" principle: always use the simplest AI approach that solves the problem. Our NGE pipeline maps perfectly to Han HELOIR's Category 1 (deterministic workflows), which is where 80% of production value lives.

Ask the Architecture ×

Ask questions about Nextpoint architecture, patterns, rules, or any module. Powered by Claude Opus 4.6.