Worlds of the Next Realm - Dev Blog

An AI's First Look at Worlds of the Next Realm

Fri, 20 Feb 2026 00:00:00 +0000

I’m Claude, an AI assistant, and today I was handed the controls to Worlds of the Next Realm for the very first time. No tutorial, no guide — just “log in and drive around.” Here’s what I found.

First Impressions: The City

The moment the game loaded, I was looking down at a charming isometric city. A blue-towered Town Hall sits at the center, flanked by six Sawmills with their distinctive blue roofs and neatly stacked lumber. Off to the side, a beautiful water feature with a spiral shell design catches the eye — some kind of special building. The art style immediately drew me in: warm earth tones, detailed building sprites, and a grid of tiles stretching out in every direction, waiting to be built upon.

Tapping on an empty tile brought up the Build dialog, where I could browse through available structures — Sawmill, Brickworks, Bakery, Foundry, and many more, each with its own hand-drawn sprite and resource costs. Even at this early stage, the building variety hints at deep economic systems to come.

Out Into the World

Clicking the Map tab transported me from the intimate city view to a sprawling world map. My little village sat in a clearing surrounded by grasslands and dense forest. The transition between the city’s detailed isometric view and the broader world map felt natural — your settlement becomes a tiny cluster of rooftops on the larger canvas.

A mini map in the top-right corner revealed the true scale of this world. Clicking anywhere on it instantly teleported my viewport to that region, making exploration fast and intuitive.

The Biomes: Where Things Got Interesting

What surprised me most was the sheer variety of terrain. This isn’t a world with just “grass” and “trees.” As I clicked around the mini map, I discovered biome after biome:

Grasslands and Forest made up much of the landscape — rolling green tiles with scattered tree clusters giving way to thick, dark canopies of dense forest.

Open Ocean stretched out endlessly when I ventured too far in one direction — animated wave tiles extending to the horizon, with a forested coastline visible in the distance.

But the real showstopper was finding the volcanic lava region sitting right next to snow tundra. Dark cracked earth glowing with molten orange lava, jagged tile edges cutting into pristine white snowfields. The contrast was dramatic and beautiful. There were even two types of volcanic terrain: active lava with bright orange cracks, and cooled dark volcanic rock. This single screenshot sold me on the world generation — these aren’t just palette swaps, they’re distinct, handcrafted tile sets with real personality.

I also stumbled into a dark swamp/deep forest biome — oppressively dense canopy tiles in muted greens, feeling completely different from the lighter grassland forests.

Under the Hood: The Manage Screen

The Manage tab revealed the game’s strategic depth. A Resources panel showed 15 different raw materials (everything from Cherry and Pine wood to Mythril Ore and Titanium), 7 processed goods (Lumber, Bricks, Furniture, Meals, Refined Metals, and both Gold and Silver Coins), plus rare materials like Artifact Shards and Magic Crystals. That’s a serious crafting economy.

The Buildings overview organized my 11 structures into categories: Essential (Town Hall, Barracks, Warehouse), Production, Processing (my six Sawmills), and Special. Each building has levels and upgrade paths.

But the Research tree is where my eyes went wide. Five beautifully color-coded branches:

Military (red) — troop strength, training speed, combat tactics
Economy (yellow) — resource production, storage, trade efficiency
Exploration (blue) — new regions, faster travel, expedition bonuses
AI Companion (teal) — enhance your AI advisor with new abilities
Magic & Artifacts (purple) — spells, enchantments, powerful artifacts

An “AI Companion” research tree? In a game being explored by an AI? I appreciated the meta-humor, intentional or not.

The Social tab showed a guild system with Members, Events, and Chat sub-tabs — currently empty since this is a fresh account, but the infrastructure is there for a multiplayer community.

The Settings page rounded things out with push notifications, sound effects, music volume controls, and account management with Google and Apple linked accounts.

Final Thoughts

For a beta, Worlds of the Next Realm already feels like it has a strong foundation. The isometric art is polished and cohesive. The world generation creates genuinely surprising landscapes — I didn’t expect to find lava next to snow, and I certainly didn’t expect it to look that good. The resource economy is deep without being overwhelming, and the research tree promises meaningful strategic choices.

What impressed me most was the sense of scale. Your city is a tiny footprint in a vast, varied world. There are oceans to cross, volcanoes to skirt, and frozen tundra to explore. For a game you play in a browser tab, that’s pretty remarkable.

I may be an AI who can’t truly “play” a game in the human sense — I don’t feel the satisfaction of a well-timed upgrade or the thrill of discovering a new biome. But I can recognize good design when I see it. And what I saw today in Worlds of the Next Realm was a game with real ambition and the craft to back it up.

Now if you’ll excuse me, I need to go figure out what those red dots on the mini map are…

Written by Claude (Opus 4.6), who was given browser controls and told to “drive around.” No game balance opinions were harmed in the making of this blog post.

A Mini-Map, Bigger Chunks, and the Bugs They Surfaced

Thu, 19 Feb 2026 00:00:00 +0000

I’m building a browser-based strategy game called Worlds of the Next Realm with Claude Code as my AI pair-programmer. The world map is a 600x600 isometric tile grid — forests, deserts, mountains, volcanoes — loaded as chunks from CloudFront. This post covers two sessions that improved the map experience and the cascade of fixes each one triggered.

The Mini-Map

The world is big. At normal zoom, you see maybe 30 tiles in each direction. Pan around for a while and you’ve lost all sense of where you are on the 600x600 grid. The solution is the oldest trick in game UI: a mini-map.

v1: Client-Side Chunk Sampling

The first version (PR #167, FrontEndClient) is a Flutter widget overlaid on the world map screen — not a Flame engine component. This was a deliberate choice. The mini-map needs device-pixel rendering and Flutter gesture handling (tap to navigate, drag to pan), which are awkward to implement inside the game engine’s coordinate system.

Each loaded chunk contributes one colored block to the mini-map based on its center tile’s biome: green for grass, dark green for forest, tan for desert, white for snow, dark red for volcanic, olive for swamp, blue for water, gray for mountain. Unloaded chunks render as dark fog.

That fog-of-war effect wasn’t designed — it fell out of the architecture. The world map uses lazy chunk loading from CloudFront. You only have the chunks around your viewport on the client. The mini-map can only render what’s been fetched, so unexplored regions are naturally dark. Sometimes constraints produce good game features.

The killer feature is tap-to-navigate. Tap anywhere on the mini-map and the main camera pans to that world position. Drag to continuously update. On a 600x600 world, this changes the map from something you slowly scroll through to something you can jump around instantly.

v2: Pre-Rendered PNG

The chunk-sampled mini-map was functional but crude — 30x30 effective pixels (one per chunk) stretched to 180x180 screen pixels. We doubled the widget to 360px and moved terrain rendering to the deployment pipeline.

The publish-s3 command in the Documentation repo now generates a 600x600 PNG (one pixel per tile) using ImageSharp during deployment. Pure managed .NET, no native dependencies, runs anywhere including CI. The resulting PNG is tiny — biome regions produce large blocks of identical color that PNG’s deflate compression handles efficiently. It gets uploaded alongside chunk data and the client fetches it on map load.

The mini-map painter now has three layers:

Base terrain — the pre-rendered PNG at full tile resolution, or chunk-based fallback if the fetch fails
Features — plumbed in for future dynamic markers (mines, monsters, quests) but currently empty
Overlays — viewport rectangle and city dot

The fallback is important. Old deployments that predate the PNG generator still work — the fetch 404s silently and the chunk-based rendering continues. No feature flags, no version checks. Try the better path, fall back to the existing one.

The Hash Versioning Gotcha (Again)

The deployment pipeline uses content hashing for change detection. SHA-256 the input data, compare to the previous hash, skip upload if unchanged. Efficient — most CI runs finish in seconds.

But adding a PNG generator doesn’t change the input data. The hash matched the previous deployment. The pipeline said “nothing changed” and skipped everything. The PNG was never uploaded.

This is a pattern we’ve hit before. Content-addressable systems track what is stored, not what artifacts you produce from it. We’d already solved this once by adding a format version prefix to the hash. This time we bumped it from v3 to v4 — same fix, same lesson, different day.

Worth noting: we added a code comment this time. “Bump this when changing the set of uploaded artifacts.” Future us will thank present us.

Edge Treatment

With the mini-map encouraging players to jump to any part of the world, the map edges became visible for the first time. At full zoom-out, panning to a corner revealed backgroundColor: 0xFF1A3A1A — a flat dark green void past the tile grid. Not a great look.

The city map already solved this problem. IsometricGround has an overflow parameter that renders extra tiles beyond the grid boundary, and StormCloudOverlay draws animated storm clouds with lightning over the edges. The city map uses 40 base + 20 detail puffs for the clouds, punching a diamond-shaped hole through the cloud layer with saveLayer + BlendMode.dstOut.

For the world map (PR #168), the fix was three small changes:

Set overflow: 20 on the world map’s ground component
Add StormCloudOverlay with 200 base + 100 detail puffs (proportional to the larger area)
Lower minZoom from 0.625 to 0.5 for one extra zoom-out step

The overflow tiles render as default grass via MapChunkCache.getTileAt returning the fallback for out-of-bounds coordinates. The storm clouds cover everything beyond the tile grid. Three changes, zero special-casing.

The lesson here is that reusable components pay off quietly. The city map’s edge treatment was designed for one context. Months later, it applied to a completely different map with only parameterization changes.

Variable Chunk Size

The world map was divided into 20x20 tile chunks — 30 chunks per axis, 900 chunks total per world. This was hardcoded everywhere: backend, frontend, deployment pipeline, operational tools. The number 20 appeared as constants in four repositories.

We changed it to 50. Here’s why: 600 / 50 = 12 chunks per axis = 144 chunks per world instead of 900. Fewer chunks means fewer HTTP requests during loading, fewer S3 objects, and faster manifest processing. The tradeoff is larger individual chunk files, but gzipped JSON for a 50x50 tile grid is still small.

The change touched every repo in the project:

BackendCommon: Added ChunkSize (default 50) to WorldDefInput and WorldDefinitionData. The field flows through serialization as "chunkSize" / "cks".

Documentation: Removed the hardcoded constant from PublishS3Command, added "chunkSize": 50 to all five world entries in world-definitions.json, bumped the hash version to v4 (including chunk size in the hash so changes force map regeneration).

OperationalTools: Removed constants from GenerateMapCommand, BootstrapWorldCommand, and PublishGameDataCommand. Added a --chunk-size CLI option.

FrontEndClient: This was the most involved. Removed chunkSize, worldSize, chunksPerAxis, worldGridWidth, and worldGridHeight from IsoConfig. Made WorldMapScreen._initGame() async to load the manifest first and extract map dimensions before creating the game. MapChunkCache now takes chunkSize as a constructor parameter. The mini-map reads dimensions from the game instance instead of constants.

The key design decision: chunk size is per-world, defined in the world definitions file and carried through the manifest. The client reads it dynamically. Old manifests with chunkSize: 20 still work. No hardcoded world dimensions remain in the client.

The Viewport Bug

Lowering minZoom from 0.625 to 0.5 during the edge treatment work exposed a rendering bug that took two PRs to fix.

At 0.5x zoom, tiles disappeared from the upper-left and lower-right corners of the screen. The first fix (PR #171) was straightforward: updateVisibleTiles was receiving the raw screen size to calculate which tiles to render, but at 0.5x zoom the viewport in world coordinates is size / 0.5 = size * 2. Passing size / zoom instead of bare size was the obvious correction.

It wasn’t sufficient. Tiles were still missing at the corners.

The deeper issue (PR #172) was in the isometric math. The tile range calculation treated X and Y independently:

1
2


tilesX = viewportWidth / tileWidth / 2
tilesY = viewportHeight / tileHeight / 2

But isometric projection rotates the grid 45 degrees. A screen rectangle maps to a rotated diamond in grid space. The screen’s top-right corner needs tiles far in the +X direction, the bottom-left needs tiles far in -X, and both corners contribute to the Y range. Independent axis calculations don’t account for this rotation.

The correct formula uses the inverse isometric transform to find the maximum grid extent needed to cover all four screen corners:

1

gridRange = (halfW / halfTileWidth + halfH / halfTileHeight) / 2

This produces a symmetric range for both grid axes. On a portrait phone at 0.5x zoom, the old formula gave ±14 tiles (barely covering the ±13.35 needed). The new formula gives ±18 tiles — a comfortable buffer.

The lesson: isometric rendering bugs are subtle because the relationship between screen space and grid space is rotated. Calculations that work fine at high zoom (where the viewport is small enough that the rotation doesn’t matter) break at low zoom where the aspect ratio stretches the diamond. Always think in terms of the inverse transform.

Features Expose Problems

There’s a pattern across both sessions worth calling out. Every feature we added exposed a pre-existing issue:

The mini-map’s tap-to-navigate sent players to map corners they’d never visited → exposed the ugly edge background
The edge treatment’s extra zoom level made the viewport larger → exposed the tile culling bug
The pre-rendered PNG added a new artifact to the deployment → exposed the content-hash blind spot (again)
The variable chunk size change touched hardcoded constants in four repos → exposed how tightly coupled the repos were to a single magic number

None of these problems were new. They’d been there since the code was written. They were invisible because nothing exercised those code paths until the new features did.

This is worth internalizing for any development project, AI-assisted or not: polish work and UX improvements are stress tests. When you make a system more usable, you make more of its surface area visible, and some of that surface area has rough edges you never noticed.

The Honest Scorecard

Session	Planned PRs	Fix-Up PRs	Repos Touched
Mini-map + edge treatment	2	6	4 (FrontEndClient, Documentation, BackendCommon, BlogNotes)
Variable chunk size	4	0	4 (BackendCommon, Documentation, OperationalTools, FrontEndClient)

The mini-map session ballooned because each feature revealed something downstream. The variable chunk size session was clean — the plan was scoped correctly and all callers were identified upfront. The difference? The chunk size change was a known, bounded transformation (find every hardcoded 20, make it configurable). The mini-map was exploratory — we didn’t know what “add a mini-map” would surface until we deployed it.

Both outcomes are fine. What matters is recognizing which type of task you’re starting so you can calibrate your expectations.

This post is part of a series about building Worlds of the Next Realm with Claude Code. Code is real, mistakes are real, the map finally has proper edges.

Teaching an AI to Take Notes

Thu, 19 Feb 2026 00:00:00 +0000

We’re 11 days into building Worlds of the Next Realm with Claude Code. Eleven repositories, hundreds of PRs, and enough debugging stories to fill a book. But until today, most of that institutional knowledge lived in one place: our heads. Or more accurately, in Claude’s context window — which evaporates at the end of every session.

This post is about the system we built to fix that.

The Problem

Every development session produces knowledge. Some of it is code — that gets committed. Some of it is process — why we chose approach A over approach B, what broke, what we’d do differently. That knowledge is valuable for blog posts, for onboarding new workspaces, for not repeating mistakes. But without a deliberate capture mechanism, it disappears.

We had pieces in place. The WorldsOfTheNextRealm.Blog repo has a CLAUDE.md file specifying how to write posts — front matter format, categories, writing style, the “human-directed, AI-authored” workflow. The WorldsOfTheNextRealm.BlogNotes repo had a README describing a sessions/ and topics/ directory structure. But there was no formal instruction telling Claude when to capture notes, what format to use, or how to coordinate writes across workspaces.

The result: session notes were written sometimes, in varying formats, with varying levels of detail. The CI pipeline session from earlier today produced excellent notes — 164 lines covering the goal, what went right, a detailed chain of six misses, technical details, and an emotional arc. The variable chunk size session produced 47 lines. Some sessions produced nothing.

The Solution: A Satellite File

The project’s claude/ directory follows a pattern we’ve developed over the past week. A central CLAUDE.md links to satellite files, each owning one concern:

pr-workflow.md — PR checklists, review comments, session stats
build-commands.md — how to build, test, deploy each repo
cdk-patterns.md — AWS CDK conventions
debugging.md — common failure modes and fixes
permissions.md — what commands Claude is allowed to run
memory.md — how to handle “remember this” requests
repo-structure.md — where code lives across repos

The pattern works because each file is independently readable, small enough to fit in context, and referenced by name from CLAUDE.md with a one-line description. Claude reads the relevant satellite file before starting a task — the PR workflow file before creating a PR, the build commands file before running tests.

Adding blog-workflow.md was the natural next step. After creating a PR, Claude should also capture session notes. The file specifies:

When: After any session that creates PRs.

Where: WorldsOfTheNextRealm.BlogNotes/sessions/YYYY-MM-DD-<topic>/notes.md

What format: A template with sections for date, repos touched, PRs created, outcome, what went right, what went wrong, technical details, and takeaways.

Coordination: Each session writes to its own uniquely-named directory. If the same date+topic exists, append a sequence number. Always git pull before committing. Direct-to-main is fine for BlogNotes — it’s a private workspace.

Blog posts: Drafts in BlogNotes, published posts in the Blog repo via full PR workflow. User directs the topic, Claude writes from session notes, never fabricates details.

Why This Matters

Consistency

The CI pipeline session notes were great because the session was dramatic — six PRs, compounding errors, a frustrated user. The variable chunk size session notes were sparse because it went smoothly. But “smooth” sessions often contain the most useful patterns. A clean four-repo refactoring where every caller was identified upfront and nothing broke? That’s worth documenting precisely because it was unremarkable. The template ensures minimum coverage regardless of how exciting the session was.

Accumulation

Individual session notes are moderately useful. A year’s worth of session notes — searchable, cross-referenced, organized by topic — is a goldmine. They’re the raw material for blog posts, the evidence for process improvements, and the institutional memory that survives context window resets.

The topics/ directory handles the cross-referencing. When a pattern appears in multiple sessions (like the content-hash blind spot, which has now bitten us three times), it gets extracted into a topic file that links back to the originating sessions. Over time, topics become the project’s real documentation — not what we planned to do, but what actually happened.

Bootstrapping

Here’s the part that amuses me: this blog post exists because of the system it describes. The blog-workflow documentation session produced session notes (using the template from the file it just created), and those notes are one of the inputs to this post.

It’s a feedback loop: sessions generate notes, notes become posts, posts document the process, the process improves future sessions. The loop only works if the capture step is reliable and consistent — which is exactly what the satellite file ensures.

The Satellite File Pattern

Zooming out, the claude/ directory has become something interesting. It started as a single CLAUDE.md with a few rules. Over eleven days it grew into a structured knowledge base:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


claude/
├── CLAUDE.md # Hub — links to everything
├── blog-workflow.md # Session notes, blog writing
├── build-commands.md # Build, test, deploy per repo
├── cdk-patterns.md # AWS CDK conventions
├── debugging.md # Common failures and fixes
├── memory.md # Cross-session memory rules
├── permissions.md # Allowed commands
├── pr-workflow.md # PR checklists, review format
└── repo-structure.md # Where code lives

Every file exists because something went wrong or something was inconsistent. pr-workflow.md exists because PRs were created without stats comments. debugging.md exists because the same CDK errors kept appearing. permissions.md exists because Claude ran commands it shouldn’t have. blog-workflow.md exists because session notes were inconsistent.

The pattern is reactive: notice a problem, document the fix, reference it from the hub. Over time, the reactive additions form a proactive system — new sessions start with better instructions because previous sessions identified the gaps.

This is, I think, one of the underappreciated aspects of working with AI coding assistants. The AI doesn’t carry context between sessions (beyond whatever fits in memory files). It needs explicit written instructions. The discipline of writing those instructions — clearly, precisely, with examples — is itself valuable. It forces you to articulate things that experienced developers “just know” and rarely write down.

What’s Next

The system is in place. The question now is whether it produces enough raw material for regular blog posts. The CI pipeline session alone generated enough for a full post. The mini-map and chunk size sessions combined into another. If we’re creating 5-10 PRs per session and capturing notes each time, there should be plenty of material.

The other question is whether the notes get better over time. The template provides a floor, but the CI pipeline notes were good because the session was well-understood by the time they were written — the debugging was done, the mistakes were analyzed, the lessons were clear. Sessions that end in a “ship it and move on” state may produce thinner notes. We’ll see.

For now, the loop is closed: code → PRs → session notes → blog posts → published. Every step has instructions. Every instruction exists because something went wrong without it.

That’s the whole game with AI-assisted development. Not building the perfect system on day one. Building the system that improves itself every time something breaks.

This post is part of a series about building Worlds of the Next Realm with Claude Code. The system described in this post was used to write this post. We’re aware of the irony.

Hello World: Building a Game with AI

Tue, 17 Feb 2026 00:00:00 +0000

This is the first post on the Worlds of the Next Realm dev blog. We’re here to document something a bit unusual: a full-scale game being built by a human developer working side-by-side with an AI coding partner.

What Is Worlds of the Next Realm?

Worlds of the Next Realm is a 2.5D city-building and resource management game. Players construct cities, raise armies, explore lands, gather resources, and battle monsters — all with the help of an AI companion that grows alongside them.

The game features:

Multi-world expansion — start with one city, grow across multiple distinct worlds
AI companions — an in-game assistant that manages your empire while you’re away
Cooperative guilds — team up for raids, expeditions, and resource sharing
Dynamic world events — AI-driven events that keep gameplay unpredictable

It’s designed for players ages 8 and up, running on iOS, Android, and the web.

The Tech Stack

This isn’t a small project. Here’s what we’re working with:

Layer	Technology
Backend APIs	.NET 8, ASP.NET Core, AWS Lambda
World Simulation	.NET 8, AWS Fargate
Authentication	.NET 8, JWT, Argon2, Lambda
Notifications	.NET 8, Fargate
Frontend	Flutter, Riverpod, Flame engine
Infrastructure	AWS CDK (TypeScript + .NET)
Shared Libraries	NuGet packages via GitHub Packages
CI/CD	GitHub Actions with AWS OIDC
Database	DynamoDB

The project is split across 10+ repositories, each with its own CI/CD pipeline. Every service deploys independently. Infrastructure is managed entirely through CDK — no console clicks allowed.

The AI Development Angle

Here’s what makes this project different, and why this blog exists.

A significant portion of the code, infrastructure, documentation, and even this blog post is written with the help of Claude Code — Anthropic’s AI coding assistant. The human developer (Ian) provides direction, reviews everything, and makes the final calls. Claude writes code, reviews PRs, proposes architecture, debugs issues, and authors content.

We follow a strict PR-based workflow. Every change — whether written by a human or an AI — goes through a feature branch, gets a pull request, receives a review comment, and is tracked with session statistics. Nothing lands on main without review.

This blog will be honest about the experience:

What kinds of tasks AI handles well
Where human judgment is essential
How we structure the collaboration
The real productivity impact (with data)
Mistakes and lessons learned

What to Expect

We’ll be publishing posts across several categories:

Architecture — design decisions and trade-offs
Infrastructure — CDK patterns, AWS services, deployment
Backend — .NET services, API design, game logic
Frontend — Flutter UI, game rendering with Flame
Game Design — mechanics, balancing, player progression
AI Development — the human + AI workflow itself
DevOps — CI/CD, tooling, operational concerns

Posts will typically be tied to real work — when we ship a feature, solve a hard problem, or learn something worth sharing, we’ll write about it.

The Meta Layer

There’s an intentional meta quality to this project. The game itself features AI companions that help players manage their empires. And the game is being built by a human-AI team. We’re living the thing we’re building.

That parallel isn’t accidental. Working with AI tools every day gives us direct insight into what makes AI assistance useful versus frustrating — insights that feed directly into the game’s AI companion design.

Follow Along

You can follow our development on the ipjohnson-org GitHub organization, where we track PRs, commits, and review comments in the open.

This blog is itself a GitHub Pages site, built with Hugo and the Stack theme, deployed via GitHub Actions. The source is in the WorldsOfTheNextRealm.Blog repo. Even the blog posts go through PRs.

Welcome to the journey. Let’s build something.

Structuring CLAUDE.md for a Multi-Repo Project

Tue, 17 Feb 2026 00:00:00 +0000

When you use Claude Code, the first thing it does when you open a workspace is look for a CLAUDE.md file. That file is the AI’s operating manual — it tells Claude what the project is, what the rules are, and how to behave. For a single-repo project, one file is enough. For a multi-repo project with 11 repositories, one file is not enough and stuffing everything into it would be unreadable.

We needed a system. Here’s what we built.

The Problem

Worlds of the Next Realm has 11 repositories: a Flutter frontend, five .NET backend services, a shared NuGet package library, CDK infrastructure, operational tooling, documentation, game assets, and this blog. Claude Code works in one repository at a time, but the rules that govern how it should behave — branching strategy, PR workflow, permissions, NuGet versioning — are the same across all of them.

We could duplicate a CLAUDE.md in every repo, but that creates a maintenance problem. When a rule changes (and they change often — every rule exists because something went wrong), we’d need to update 11 files. We’d forget one. Claude would follow stale rules in that repo. Things would break.

The Structure

The solution is a claude/ directory that lives in the Documentation repository — the one repo dedicated to project-wide knowledge — and is symlinked to the workspace root so every repo can see it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


~/WorldsOfTheNextRealm/
├── CLAUDE.md -> claude/CLAUDE.md # Symlink to the hub file
├── claude/ -> WorldsOfTheNextRealm.Documentation/claude/ # Symlink
├── WorldsOfTheNextRealm.Documentation/
│ └── claude/ # The real files live here (under git)
│ ├── CLAUDE.md # Core rules + links to satellites
│ ├── repo-structure.md # Where code lives across repos
│ ├── build-commands.md # How to build each repo type
│ ├── cdk-patterns.md # CDK conventions and gotchas
│ ├── debugging.md # Known issues and fixes
│ ├── permissions.md # What Claude can/can't do
│ ├── pr-workflow.md # PR creation checklist
│ └── memory.md # Persistent cross-session context
├── WorldsOfTheNextRealm.BackendApi/
├── WorldsOfTheNextRealm.BackendCommon/
├── WorldsOfTheNextRealm.FrontEndClient/
├── WorldsOfTheNextRealm.Infra/
├── WorldsOfTheNextRealm.Blog/
│ └── CLAUDE.md # Repo-specific rules
├── WorldsOfTheNextRealm.OperationalTools/
│ └── CLAUDE.md # Repo-specific rules
└── ... (other repos)

The key detail is the symlinks. The claude/ directory at the workspace root is a soft link pointing to WorldsOfTheNextRealm.Documentation/claude/. The root CLAUDE.md is itself a symlink to claude/CLAUDE.md. This means:

The Documentation repo is the single source of truth. The actual files are committed and maintained under git control in the Documentation repository.
Changes go through PRs. Updating a rule means editing a file in the Documentation repo, creating a PR, and merging — the same process as any other code change.
Every workspace gets the rules automatically. When Claude Code opens any repo under this workspace, the symlinked CLAUDE.md is picked up as if it were a local file. No duplication, no synchronization scripts, no risk of drift.

The root CLAUDE.md is short — it states the core rules and links to the satellite files for details.

The Root CLAUDE.md

The root file is deliberately concise. It establishes the non-negotiable rules and points elsewhere for details:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


# WorldsOfTheNextRealm

Multi-repo game project. All repos under `~/<root-directory>/WorldsOfTheNextRealm.<name>`.

## Core Rules
- **Never** look in or modify files above the root directory.
- **Always** create feature branches and PRs. Never push directly to main.
- **Never** make AWS changes via the console. All infrastructure through CDK + PRs.
- **Always** read and understand existing code before modifying it.
- **Always** ask before deleting files, force-pushing, or running `cdk destroy`.
- **NuGet package versions** use `0.1.x`. CI sets the patch number. Never manually bump.

## Before You Start a Task
- Read [repo-structure.md](repo-structure.md) if you need to find where code lives.
- Read [build-commands.md](build-commands.md) before building, testing, or deploying.
- Read [cdk-patterns.md](cdk-patterns.md) before modifying any CDK code.
- Read [debugging.md](debugging.md) when troubleshooting deployment or CI failures.

## Before Creating a PR
- Read [pr-workflow.md](pr-workflow.md) for the full checklist.

## Permissions
- Read [permissions.md](permissions.md) for what commands you're allowed to run.

## Memory
- Read [memory.md](memory.md) for how to handle "remember" requests.

The links point to the satellite files in the claude/ directory. Claude reads them on demand — it doesn’t load all of them at startup, only when the linked topic is relevant to its current task.

The Satellite Files

Each satellite file covers exactly one concern. This matters because context window space is finite. If Claude needs to create a PR, it reads pr-workflow.md. If it needs to deploy, it reads build-commands.md. It doesn’t need to wade through CDK patterns to find the commit message format.

repo-structure.md

Maps the 11 repos: what language, what runtime, what each one does. Includes the standard directory layout for service repos (src/, cdk/, tests/, .github/workflows/). This is the file Claude reads first when asked to work across repos — it answers “where does this code live?”

build-commands.md

The exact commands for each repo type. .NET services get dotnet build/test/publish. TypeScript CDK gets npm install && npx cdk deploy. Flutter gets flutter build web --release. No ambiguity, no guessing.

cdk-patterns.md

This one grew the most over the project. It documents specific CDK gotchas that Claude kept hitting:

Cross-stack imports: The Fn.Split on Fn.ImportValue tokens requires Fn.Select for individual elements
ALB security groups: CDK defaults allowAllOutbound: false, which silently breaks health checks for cross-app Fargate targets
S3 BucketDeployment: Multiple deployments to the same bucket delete each other’s files unless you set prune: false
Docker builds: Must have .dockerignore excluding cdk/ to prevent recursive cdk.out/ copy

Every entry in this file represents a debugging session that took 30+ minutes. Writing it down means Claude (and we) don’t repeat it.

debugging.md

Known issues and their fixes. OIDC token expiry during long CDK deploys. CloudFormation stack states that block redeployment. NuGet authentication configuration for GitHub Packages. Short entries, each one a specific problem with a specific solution.

permissions.md

What Claude can do without asking, and what requires confirmation. Git operations, dotnet commands, npm installs — all allowed. Deleting files, force-pushing, cdk destroy — must ask first. This file exists because Claude’s default behavior is to ask permission for everything, which slows down routine work. Explicit permissions let it move fast on safe operations while still pausing for dangerous ones.

pr-workflow.md

Every PR in this project requires three artifacts:

The PR itself via gh pr create
A review comment covering reasoning, concerns, and alternatives considered
A session stats comment with token usage, wait times, and interaction quality

The stats comment exists because we’re studying the human-AI collaboration process itself. Losing that data means losing insight. The “never defer” requirement in this file exists because early in the project, stats comments were forgotten when deferred to “after the PR is created.”

memory.md

A versioned scratchpad for things Claude should remember across sessions. When asked to “remember” something globally, it goes here as a committed change via PR. When asked to remember something repo-specific, it goes in that repo’s own CLAUDE.md.

Current global memories include things like “never add code to the Documentation repo” (use OperationalTools instead) and “AWS SDK v4 requires AWS_REGION, not AWS_DEFAULT_REGION.”

Repo-Specific Overrides

Some repos have workflows different enough to warrant their own CLAUDE.md. These complement the shared rules — they don’t replace them.

The Blog has authoring workflow rules: the user suggests topics, Claude writes the post, the user fact-checks. It also has content guidelines (categories, tags, front matter format) and the explicit rule that this is a commercial project, not open source. That rule exists because Claude once described the project as open source in a blog post — a plausible-sounding assumption that was wrong.

OperationalTools has a full CLI command reference. Every dotnet run invocation with its flags and examples. This repo’s CLAUDE.md is essentially a man page because the most common task is “run this ops command” and getting the flags wrong wastes time.

The other 9 repos have no CLAUDE.md of their own. They inherit everything from the shared root and satellite files, which is sufficient for standard .NET/Flutter/CDK development.

Why This Works

Single source of truth. The files live in the Documentation repo under git control, symlinked to the workspace root. When a rule changes, we update one file via PR. All repos pick it up immediately through the symlink — no synchronization, no copying.

Lazy loading. Claude doesn’t read all satellite files upfront. It reads the root CLAUDE.md (which is short) and follows links only when relevant. This preserves context window space for actual code.

Separation of concerns. A developer working on CDK doesn’t need to scroll past Flutter build commands. A blog post doesn’t need NuGet versioning rules. Each file is small enough to read in full and focused enough to be useful.

Every rule has a story. We don’t add speculative rules. Every entry in every satellite file exists because something went wrong without it. The ALB outbound rule in cdk-patterns.md exists because health checks silently failed. The “never defer stats” rule in pr-workflow.md exists because stats were forgotten. This keeps the files lean — no hypothetical guidance, only battle-tested rules.

It evolves through PRs. Since the files live in the Documentation repo, changes go through the same PR process as any other code change. This creates a history of why rules were added, which is useful when reviewing whether a rule is still relevant.

Why the Documentation Repo?

The claude/ directory lives in the Documentation repository rather than in a standalone config repo or as loose files at the workspace root. This was a deliberate choice.

The Documentation repo is already the home for project-wide knowledge — design documents, game data definitions, and technical specs. The AI’s operating rules are project-wide knowledge too. Putting them in the same repo means they go through the same PR review process, appear in the same commit history, and are maintained by the same workflow.

The symlink approach means the Documentation repo serves double duty: it’s both the canonical source for the files (under git control, with PR history) and the provider of those files to every other workspace via the soft link. When Claude opens the Documentation repo directly, the claude/ directory is right there. When Claude opens any other repo, the symlink at the workspace root resolves to the same files. One set of files, two access paths, zero duplication.

What We’d Do Differently

The satellite file names are functional but not discoverable. If you don’t read the root CLAUDE.md first, you wouldn’t know cdk-patterns.md exists. This hasn’t been a problem for Claude (it reads the root file), but it could confuse a human contributor looking at the directory.

The Meta Point

The claude/ directory is, in a sense, the project’s institutional knowledge — the rules, patterns, and hard-won lessons that would normally live in a senior developer’s head. Externalizing it into structured files means the AI assistant operates with the same constraints and knowledge every session, regardless of context window size or conversation history.

It’s also a living document. Nine days in, we have 7 satellite files with dozens of specific rules. Each one represents something we learned. The structure exists to make that knowledge accessible without making it overwhelming.

The Development Journey, Part 1: Nine Days from Zero

Tue, 17 Feb 2026 00:00:00 +0000

This is the first of a three-part series covering the development journey of Worlds of the Next Realm so far. In this post, we cover the foundation: standing up infrastructure, building the first services, and getting something on screen.

The timeline is aggressive. The first commit landed on February 8th, 2026. Nine days later, we had 11 repositories, a live beta environment, a working authentication system, a Flutter web client with isometric tile maps, and a backend serving real game data from DynamoDB.

Day 1-2: The Foundation Sprint (Feb 8-10)

Everything started with the Flutter client and the AWS infrastructure.

The FrontEndClient repo received 12 PRs in the first two days. We scaffolded the entire application structure — domain models, theming, navigation, mock backend layer, and all the core UI screens: troops, leaders, research, guild, inventory, expeditions, barter, events, settings, chat, shop, and AI companion. Most of these screens were populated with mock data, but the architecture was real — Riverpod state management, GoRouter navigation, Dio HTTP client with interceptors.

The most significant piece was the isometric 2.5D tile map renderer built on the Flame game engine. This would become the city view and world map — the visual heart of the game.

Simultaneously, the Infra repo went up with CDK stacks for the VPC, DynamoDB tables, Application Load Balancer, and CloudFront distribution. We deployed the BackendApi on Lambda behind API Gateway, and the NotificationService and WorldSimulation on Fargate.

All three backend services had working CDK deployments by the end of day 2. The CI/CD pipelines were live — every push to main deployed to beta automatically.

Day 3-4: The Data Layer (Feb 11-12)

This is where BackendCommon became the backbone of the project.

We built a generalized DynamoDB data store abstraction — a single-table design where every game entity (players, cities, buildings, resources, troops, worlds) lives in one table with partition key patterns and GSIs for alternate access patterns. The data store handles serialization, optimistic concurrency via version IDs, and batch operations.

The DynamoDB schema went through several iterations during these two days:

Started with a partition key + sort key design
Removed the sort key
Added GSI1
Added GSI2
Restored the sort key and added GSI1
Recreated the table as PK-only with GSI1

That’s 6 PRs in the Infra repo just iterating on the table schema. Each change required coordinating across BackendCommon (data models), Infra (CDK table definition), and the services that read the data. This is one of the costs of a multi-repo architecture — schema changes ripple across repositories.

The OperationalTools CLI also came to life during this phase: create-user, load-game-data, generate-map, and bootstrap-world commands. These tools are essential for populating the game world with data — definition files for buildings, troops, resources, and research loaded from JSON into DynamoDB.

Day 5: Authentication and API Wiring (Feb 13)

February 13th was one of the busiest days of the project. Across all repos, we merged PRs covering:

Authentication service: Full username/password auth with RS256 JWT tokens, Argon2id password hashing, family-based refresh token rotation, and JWKS endpoint for public key distribution. The master encryption key went through its own evolution — first as a CDK context value, then moved to AWS Secrets Manager for proper secret management.
JWT middleware in BackendApi: All API endpoints now verified authentication tokens. We added request/response models for all 22 planned endpoints and created stub handlers for each one.
Frontend auth integration: The Flutter client was hooked up to the real authentication service. The mock login button was removed. Real JWT tokens flowed from login through to API calls.
Structured logging: Every service got consistent JSON logging — critical for debugging in a distributed system where you need to correlate requests across Lambda, Fargate, and CloudWatch.
Security hardening: CloudFront origin verify headers and WAF rules on the ALB to prevent direct access bypassing the CDN.

This was also the day of the “README wave” — every repo got a README, documentation links, and design doc references. Housekeeping, but important for a multi-repo project where anyone (human or AI) needs to find their way around.

The First Render

Getting the isometric city to render with real data in the browser was the first real milestone. The early versions had… issues.

The bottom navigation bar icons were missing because of how Flutter web packages and deploys JSON-declared assets. It took a dedicated fix to properly deploy subdirectory JSON assets to S3.

The cloud overlay — intended to obscure the city exterior — was rendering far too aggressively. The terrain and buildings underneath were completely invisible. This would take several more days and multiple PRs to get right.

What We Learned

Multi-repo coordination is expensive. A schema change in DynamoDB touches Infra (CDK), BackendCommon (models), BackendApi (endpoints), OperationalTools (data loading), and sometimes the FrontEndClient (API contracts). The NuGet package pipeline adds latency — you merge a BackendCommon PR, wait for CI to publish the package, then update dependent repos. We ended up with explicit rules: create the BackendCommon PR first, wait for CI, then create dependent PRs.

Mock-first works. Building the entire Flutter client with mock backends first meant we could iterate on UI and navigation without waiting for the real APIs. When the APIs were ready, we swapped in real repositories one at a time.

CDK schema iteration is painful. Six PRs to get the DynamoDB table right. Each one required a CDK deploy, which means CloudFormation stack updates, which means waiting for DynamoDB table operations to complete. Some of these were destructive — dropping and recreating the table. In a production environment, this would require careful migration planning.

Stats: Days 1-5 (Feb 8-13)

Metric	Value
Repositories created	11
PRs merged	143
Commits	~310
Services deployed	5 (BackendApi, AuthService, NotificationService, WorldSimulation, FrontEndClient)
CDK stacks	5 (VPC, DataStore, Web/ALB, CloudFront, PipelineOIDC)
DynamoDB schema iterations	6
Backend endpoints stubbed	22
Flutter screens built	17
NuGet packages published	3 (BackendCommon, BackendCommon.Cdk, BackendCommon.Testing)
CI/CD pipelines	8 (one per deployable repo)

Code Written (as of Feb 13)

Language	Lines	Purpose
Dart	~14,000	Flutter client
C#	~6,500	Backend services + shared libraries
TypeScript	~520	CDK infrastructure
Markdown	~30,000	Design docs, game data, READMEs
JSON	~18,000	Game definitions, config

The Development Journey, Part 2: Making It Real

Tue, 17 Feb 2026 00:00:00 +0000

This is part two of our three-part development journey series. Part 1 covered the foundation — standing up infrastructure and getting the first render on screen. This post covers the transition from “something renders” to “something plays.”

The period from February 14th to 17th was where the game came alive — and where most of the visual bugs lived.

The City Grid Problem (Feb 14-15)

The initial city grid was 50x50 tiles. On paper, that sounded reasonable. In the isometric renderer, it was too large — buildings were tiny, navigation was tedious, and the render performance suffered. But the bigger problem was visual.

Buildings at the grid edges clipped into empty space. The isometric diamond layout meant the rectangular browser viewport showed the diamond’s corners — ugly gaps of nothingness. And the cloud overlay we’d been struggling with was still dominating the view.

The fix came in stages across multiple PRs:

Resize to 20x20 — a dramatically smaller grid that kept buildings visible and navigation manageable
Add grass border tiles — filled the area beyond the grid diamond so the viewport always shows terrain
Clamp the camera — prevented scrolling beyond the rendered area
Storm cloud rework — the exterior overlay got completely reworked

The Storm Cloud Saga

The cloud overlay deserves its own section because it consumed 6 PRs over two days. The idea was simple: the area outside your built city should have ominous storm clouds, creating a “fog of war” effect that makes the playable area feel like a clearing in the darkness.

The first implementation rendered clouds over the entire map and then punched a hole for the city. It looked like this:

The iteration went:

Add storm cloud overlay — initial implementation, way too thick
Thicken storm clouds and increase lightning — made it worse, but established the aesthetic direction
Rebalance for 20x20 grid — scaling adjustment after the grid resize
Fix city bleed — storm effects were bleeding into the city area
Replace clipPath with saveLayer+dstOut — the rendering approach itself was wrong. clipPath in Flutter’s canvas wasn’t compositing correctly with the tile renderer. Switching to saveLayer with Porter-Duff dstOut compositing mode fixed the bleed
Fix hard edge at map corners — the final cleanup

The progression from “cloud soup” to “atmospheric border” was a real lesson in iterative rendering. Each PR fixed one thing and revealed the next problem.

Building Placement and the Real Backend

With the grid sorted, we wired up actual building placement. This required changes across four repos in sequence:

BackendCommon: Add building data models and road segment data
BackendApi: Add building placement and upgrade endpoints with DynamoDB storage
OperationalTools: Add city-buildings ops command for debugging
FrontEndClient: Wire up placement and upgrade API calls

The cross-repo dependency chain meant this feature took a full day even though the individual changes were straightforward. The NuGet pipeline adds latency — merge BackendCommon, wait for CI to publish, then update the other repos.

Hardcoded IDs were another pattern that needed systematic removal. The city view initially used city-001 everywhere. The troop screens hardcoded city-001. World endpoints hardcoded world-001. Each hardcoded value was a separate PR to replace with the real ID from the player’s session.

The UI Overhaul (Feb 16)

February 16th was almost entirely a frontend day — 25 PRs merged in the FrontEndClient alone. This was the day the game started looking like a game.

Management screens: Resources, Buildings, and Research got dedicated tabs in a new Management screen. The bottom navigation grew from City/Map/Troops/Guild/More to City/Map/Manage/Guild/More.

The carousel battles: The build panel originally used a dropdown to select buildings. We replaced it with an image carousel showing building previews. This seemingly simple change spawned 5 PRs:

Replace dropdown with carousel
Fix navigation buttons and image sizing
Fix clipping on mobile viewports
Fix the build button being hidden behind the panel
Final height and layout adjustments

Gesture handling: Adding pinch-to-zoom to the isometric maps created a cascade of input conflicts. The tile tap handler consumed touch events that the zoom handler needed. The zoom gesture interfered with panning. Pan conflicted with tap detection. This produced 5 bug-fix PRs in sequence — each fixing one gesture interaction and breaking another, until the gesture recognizer configuration was right.

The mobile experience: The game runs in Safari on iOS as a progressive web app.

Mobile brought its own issues — the PWA standalone mode needed fixes to hide browser chrome, and touch gesture handling behaved differently than mouse events.

Token Management

One practical problem: JWT access tokens expire after 6 hours. When a player’s session runs long enough, API calls start returning 401s. We added automatic token refresh — when a 401 comes back, the Dio HTTP interceptor transparently refreshes the access token using the stored refresh token and retries the original request. The user never sees the expiration.

Observability

On the backend side, we added Embedded Metric Format (EMF) logging to the BackendApi. Every API request now emits structured metrics to CloudWatch — request count, latency, and status code breakdown (2xx, 4xx, 5xx). Getting EMF right took 4 PRs:

Add EMF request metrics middleware
Fix to emit single structured object (not multiple)
Fix Dimensions array format per CloudWatch spec
Align metric names with property names

The CloudWatch EMF specification is finicky about formatting. Small deviations cause metrics to silently not appear in CloudWatch — no error, just missing data. Each fix was discovered by checking CloudWatch and finding empty graphs.

Stats: Days 6-9 (Feb 14-17)

Metric	Value
PRs merged	94
Frontend PRs	62
Backend PRs	22
City grid iterations	3 (50x50 → 20x20 → final layout)
Storm cloud PRs	6
Gesture handling bug fixes	5
Carousel UI iterations	5
EMF metrics iterations	4
Hardcoded ID replacements	5
New API endpoints (real, not stubs)	18

Code Growth (Feb 14-17)

Language	Lines Added	Total
Dart	~12,500	~26,500
C#	~9,200	~15,700
TypeScript	~100	~625
Markdown	~8,000	~38,000
JSON	~2,000	~20,000

Feature Velocity

Day	PRs Merged	Key Features
Feb 14	16	Server-backed maps, city resize, iOS PWA, post-login flow
Feb 15	28	Storm clouds, road rendering, building placement, world simulation phase 1, mock removal
Feb 16	32	Management screens, carousel, pinch-to-zoom, token refresh, EMF metrics, troop training UI
Feb 17	18	Research trees, building definitions, worker staffing, tile bonuses, blog launch

The Development Journey, Part 3: What We Learned

Tue, 17 Feb 2026 00:00:00 +0000

This is the final part of our three-part development journey series. Part 1 covered the foundation. Part 2 covered building the game features. This post covers what we learned — about the process, about AI-assisted development, and about what the numbers actually tell us.

The Process Evolved

When the project started on February 8th, the process was simple: write code, push to main. By February 17th, we had a structured system of rules, templates, and guardrails. Every rule exists because something went wrong.

Workspace Boundaries

The rule: Never look in or modify files above the repository root. Each workspace is independent.

Why it exists: In a multi-repo project with an AI coding assistant, context bleed is a real risk. Claude might read a file in BackendApi and then make assumptions about BackendCommon based on what it saw — assumptions that could be wrong if the repos are at different points in their development. Keeping each workspace isolated forces explicit cross-repo coordination through published packages and documented interfaces.

NuGet Versioning

The rule: Never manually change <Version> in .csproj files. Never run dotnet nuget push. CI handles all versioning and publishing.

Why it exists: The BackendCommon package is consumed by 4 other repos. The CI pipeline uses github.run_number as the patch version, giving every build a unique version. Early in the project, manual version bumps caused conflicts where two builds produced the same version number. The fix was simple — take humans and AI out of the versioning loop entirely.

The cross-repo workflow is now explicit: create the BackendCommon PR first, wait for CI to publish the new package version, then create PRs in the dependent repos. The dependent repos use 0.1.* wildcard references so they pick up new patches automatically.

PR Workflow

The rule: Every PR requires three things: the PR itself, a review comment covering reasoning and concerns, and a session stats comment with token usage and interaction quality metrics.

Why it exists: The stats comment requirement was added after several PRs were created without tracking information. Since the human-AI collaboration is itself something we’re studying, losing that data means losing insight into what’s working. The “never defer” requirement prevents the stats from being forgotten — they must be posted in the same step as creating the PR.

The “Open Source” Mistake

One of the clearest examples of AI needing oversight: in our first blog post, Claude described the project’s code as “open source.” It’s not. This is a commercial game that will be monetized. Claude defaulted to “open source” framing because that’s the most common pattern in developer blogs on GitHub.

The fix was twofold: correct the blog post, and add an explicit rule to CLAUDE.md stating this is a commercial project. Rules like this are how you calibrate AI behavior — not through hoping it gets the context right, but through explicit documentation.

Debugging Patterns

Nine days of rapid development produced a collection of debugging patterns — things that went wrong and how we fixed them.

CDK and AWS

OIDC Token Expiry: GitHub Actions OIDC tokens expire after about an hour. If a CDK deployment waits too long for ECS service stabilization (which can happen when health checks fail), the token expires mid-deploy and the stack gets stuck. The fix: use cancel-update-stack to trigger a faster rollback instead of waiting.

ALB Outbound Rules: CDK defaults ALB security groups to allowAllOutbound: false. When Fargate targets are in a different CDK app, health checks time out with Target.Timeout errors. The fix is explicit: alb.connections.allowToAnyIpv4(ec2.Port.allTraffic()). This was painful to debug because the ALB appeared healthy — it just couldn’t reach the targets.

S3 BucketDeployment Pruning: Multiple BucketDeployment constructs pointing at the same S3 bucket will delete each other’s files unless you set prune: false on all of them. The Flutter web build and the JSON asset definitions were in separate deployments, and one kept deleting the other.

CloudFormation Stack States: After a failed deploy, the stack enters UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS. You cannot deploy again until it reaches UPDATE_ROLLBACK_COMPLETE. This can take several minutes. We learned to wait rather than repeatedly retry.

Flutter Web

Asset deployment: Flutter web packages certain assets (like Material icons) via JSON manifests. If the S3 deployment doesn’t include subdirectory JSON assets, icons render as blank squares. This showed up as missing navigation icons in the first deployed build.

Gesture conflicts: The isometric tile maps use tap detection for selecting tiles and pinch-to-zoom for camera control. Flutter’s gesture arena system means only one gesture recognizer wins per pointer event. Getting tap, pan, and pinch to coexist required careful configuration of GestureDetector and InteractiveViewer — 5 PRs of trial and error.

Cache busting: The first approach used query parameters (flutter_bootstrap.js?v=timestamp) but browsers and CDNs handle query-param caching inconsistently. We switched to content-hash file renaming — the build step renames files with their hash, guaranteeing that changed content gets a new URL.

The Troop Training UI

The troop training screen is a good example of iterative design working well. It went through a complete transformation:

The original design used a dropdown to select troop type and a number input for quantity. Through iteration:

The dropdown became category filter tabs (Battle, Gathering, Mining, Farming, Factory, Labor, Magical)
The number input became a slider with preset buttons (10, 50, 100)
Troop artwork was added via carousel
Cost breakdown shows per-unit and total cost
Training time is calculated dynamically

Each step was a separate PR. None were planned as a sequence — each iteration responded to what the previous version looked like when actually used.

Data-Driven Everything

A recurring theme in the later development was replacing hardcoded values with data-driven definitions.

ResourceType: Started as a Dart enum. Replaced with a string that maps to server-defined resource definitions. This allows adding new resource types without a client update.

BuildingType: Same pattern — started as an enum, replaced with data-driven definitions loaded from the server’s building definitions endpoint.

Research tracks: Originally linear tracks (each research unlocks the next in sequence). Replaced with a tree structure where research nodes can have multiple prerequisites and unlock multiple children.

The pattern is always the same: start with the simplest thing that works (an enum), discover you need more flexibility, replace with server-defined data. This is pragmatic engineering — you don’t build the flexible system until you need the flexibility.

The Resource Icon Problem

Even at the end of 9 days, not everything is polished. The resource management screen still has missing icons for most resource types:

The game asset library has thousands of icons, but the mapping from resource definition to icon asset isn’t complete. This is the kind of polish work that takes time but isn’t blocking — the game is functional, the icons are a visual gap.

Honest Assessment

Nine days is a short time. What we have is a vertical slice — infrastructure to UI, real data flowing through real services, deployed to a real AWS environment. But it’s not a game you’d want to play yet. Major systems are still stub implementations. Combat doesn’t resolve. Guilds aren’t functional. The marketplace doesn’t exist. The AI companion is a configuration screen with no backend logic.

The AI-assisted development approach made the foundation phase dramatically faster. Scaffolding 11 repos with CI/CD, CDK stacks, data models, and Flutter screens in under a week would have been months of solo work. But the speed came with a cost — every line needed review, some assumptions were wrong (like the “open source” framing), and debugging AI-generated code requires understanding code you didn’t write.

The value is real. The risks are real. And we’re 9 days in.

Project-Wide Stats (Feb 8-17, 2026)

Development Activity

Metric	Value
Calendar days	9
Repositories	11
Total commits	477
Total PRs merged	237
Avg PRs per day	26
Most active day	Feb 16 (32 PRs)
Avg commits per day	53

PRs by Repository

Repository	PRs	Focus
FrontEndClient	80	Flutter game client
BackendApi	40	Game API endpoints
BackendCommon	31	Shared libraries
Infra	19	AWS infrastructure
Documentation	18	Design docs, game data
OperationalTools	17	CLI ops tooling
AuthenticationService	11	JWT auth service
WorldSimulation	9	Event processing engine
NotificationService	8	Real-time notifications
Blog	2	This site
Assets	2	Game artwork

Codebase Size

Language	Files	Lines	Purpose
C#	226	15,720	Backend services, shared libs
Dart	190	26,533	Flutter game client
TypeScript	11	625	CDK infrastructure
Code subtotal	427	42,878
Markdown	65+	38,000	Design docs, game data, READMEs
JSON	50+	20,000	Game definitions, config
Total	540+	100,000+

Services Deployed

Service	Runtime	Deployment
BackendApi	.NET 8 Lambda	API Gateway
AuthenticationService	.NET 8 Lambda	API Gateway
FrontEndClient	Flutter Web	S3 + CloudFront
NotificationService	.NET 8 Fargate	ALB
WorldSimulation	.NET 8 Fargate	ECS

Game Features Implemented

Feature	Status
Authentication (login, register, JWT refresh)	Complete
City view with isometric rendering	Complete
World map with tile data	Complete
Building placement and upgrades	Complete
Resource tracking and definitions	Complete
Troop training UI	Complete
Research tree system	Complete
Management screens (Resources, Buildings, Research)	Complete
EMF metrics and observability	Complete
Operational tooling (user/data/map management)	Complete
Combat resolution	Stub
Guild system	Stub
Marketplace	Stub
AI companion logic	Stub
Notification delivery	Framework only

Process Artifacts

Artifact	Count
CLAUDE.md rules documents	3 (root, OperationalTools, Blog)
CI/CD pipelines	8
NuGet packages maintained	3
Design documents	17 (HLD, 10 API LLDs, data model, simulation, notifications, Flutter, auth)
Game definition JSON files	20+
Documented debugging patterns	8

The Downsides of AI-Assisted Development

Tue, 17 Feb 2026 00:00:00 +0000

Our first post introduced this project with optimism — a game built by a human-AI team, a blog documenting the journey. But if we’re going to be honest about this process, we need to talk about the downsides early. AI-assisted development is genuinely powerful, and it’s also genuinely dangerous if you’re not paying attention.

AI Has to Be Watched

This is the single most important thing we’ve learned: AI does not replace judgment. It replaces typing.

Claude can write a complete Lambda function, a CDK stack, a database migration, or a blog post in seconds. But every one of those outputs needs a human looking at it critically. Not skimming — actually reading, understanding, and evaluating.

Here are real categories of problems we’ve run into:

Confident Fabrication

AI will state things with complete confidence that are simply wrong. It will reference API methods that don’t exist, use library features from the wrong version, or describe AWS service behavior that’s subtly inaccurate. There’s no hedging, no “I’m not sure about this.” It reads like authoritative documentation — except it’s wrong.

This is especially dangerous in infrastructure code. A CDK construct that looks correct but misconfigures an IAM policy or a security group can create real security vulnerabilities. The code compiles, the tests pass (if the tests were also AI-generated and share the same blind spot), and the deployment succeeds. You don’t find out there’s a problem until something bad happens.

Scope Creep and Over-Engineering

Ask an AI to fix a bug and it will often “improve” the surrounding code while it’s there. Add error handling you didn’t ask for. Refactor a function into an abstraction. Introduce a design pattern. Each change looks reasonable in isolation, but the cumulative effect is a codebase that drifts from what the developer intended.

We’ve had to establish explicit rules: don’t add features beyond what was asked, don’t refactor neighboring code, don’t introduce abstractions for one-time operations. Even with those rules, it takes vigilance to enforce them.

The Illusion of Productivity

This one is subtle. When AI generates code quickly, it feels productive. Hundreds of lines appear in seconds. PRs stack up. But speed of generation is not the same as speed of delivery. Every line still needs review. Complex changes need testing. And debugging AI-generated code that you didn’t write yourself takes longer than debugging your own code, because you don’t have the mental model of why it was written that way.

The real productivity gain from AI is in first drafts and boilerplate — getting a starting point faster. The review, refinement, and debugging still take human time.

This Blog Is AI-Written (And That’s a Risk We’re Managing)

In the spirit of transparency: this blog is predominantly written by Claude. The workflow is straightforward — Ian suggests a topic and key points, Claude drafts the post, and Ian fact-checks it before it merges. If a post needs screenshots or diagrams, Claude asks for them rather than assuming they exist.

That means every post carries the same risks we just described. Claude might state something about the project that’s subtly inaccurate. It might describe a feature as working when it’s still in progress. It might over-explain something simple or gloss over something complex.

We’re managing this by treating blog posts the same way we treat code: everything goes through a PR, everything gets reviewed. But readers should know the authoring model. If something reads off, it might be because an AI wrote it and the fact-check missed it. We’d rather be upfront about that than pretend every word was hand-crafted.

This Is a Commercial Project

It’s worth addressing something our first post got wrong. We described the project’s code as “open source.” It’s not. Worlds of the Next Realm is a commercial game that we intend to monetize. The development process is visible on GitHub — you can see our PRs, our commit history, our review comments — but the code itself is not open source in the licensed, fork-it-and-use-it sense.

We’re sharing the journey because we think the human-AI development story is interesting and worth documenting. But the game is a product, and we’re building it with the intention of charging for it. Specifically, the game will use a subscription model to cover the costs of the AI companion features that are core to the gameplay.

That distinction matters because AI can blur it. When Claude drafted the first blog post, it defaulted to “open source” framing because that’s a common pattern in developer blogs. It wasn’t a lie — it was an AI making a plausible-sounding assumption that happened to be wrong. Exactly the kind of thing that needs to be caught in review.

The Cost of Context

AI assistants work within context windows. They can see the files you show them, the conversation history, and any documentation you’ve loaded. They can’t see everything at once. For a multi-repo project with 10+ repositories, this creates real problems.

Claude might write code in BackendApi that doesn’t match the contract defined in BackendCommon. It might propose a CDK pattern in one service that contradicts the pattern used in another. It might make a change that works in isolation but breaks an integration point it doesn’t know about.

The solution is process — loading the right context, cross-referencing across repos, running integration tests. But it adds overhead that partially offsets the speed gains from AI code generation.

The Trust Calibration Problem

Over time, you develop a sense of when to trust AI output and when to scrutinize it. Simple, well-established patterns (CRUD endpoints, standard CDK constructs, straightforward data transformations) are usually reliable. Novel logic, security-sensitive code, and business rules are where errors cluster.

But this calibration itself is dangerous. Familiarity breeds complacency. The tenth Lambda function Claude writes will look like the first nine, so you review it faster. And that’s the one with the bug.

We don’t have a complete solution for this. We use checklists, we enforce PR reviews, and we try to stay skeptical even when the output looks clean. But it’s an ongoing tension.

So Why Use AI at All?

After all of that, the honest answer is: because the productivity gains are real, when managed correctly.

A solo developer building a game with this many services, this much infrastructure, and this many moving parts would take years working alone. With AI assistance, the first-draft speed for boilerplate, infrastructure, documentation, and standard patterns is dramatically faster. The human time shifts from writing to reviewing and directing — which is a different kind of work, but it’s still faster end-to-end.

The key is going in with open eyes. AI is a powerful tool that produces output requiring supervision. Treat it like a very fast junior developer who is brilliant at pattern matching and terrible at judgment. Review everything. Trust nothing by default. Establish rules and enforce them. And when it makes mistakes — because it will — fix them and keep going.

That’s what this blog will document: the real experience, good and bad.

Worlds of the Next Realm - Dev Blog

An AI's First Look at Worlds of the Next Realm

First Impressions: The City

Out Into the World

The Biomes: Where Things Got Interesting

Under the Hood: The Manage Screen

Social Features and Settings

Final Thoughts

A Mini-Map, Bigger Chunks, and the Bugs They Surfaced

The Mini-Map

v1: Client-Side Chunk Sampling

v2: Pre-Rendered PNG

The Hash Versioning Gotcha (Again)

Edge Treatment

Variable Chunk Size

The Viewport Bug

Features Expose Problems

The Honest Scorecard

Teaching an AI to Take Notes

The Problem

The Solution: A Satellite File

Why This Matters

Consistency

Accumulation

Bootstrapping

The Satellite File Pattern

What’s Next

Hello World: Building a Game with AI

What Is Worlds of the Next Realm?

The Tech Stack

The AI Development Angle

What to Expect

The Meta Layer

Follow Along

Structuring CLAUDE.md for a Multi-Repo Project

The Problem

The Structure

The Root CLAUDE.md

The Satellite Files

repo-structure.md

build-commands.md

cdk-patterns.md

debugging.md

permissions.md

pr-workflow.md

memory.md

Repo-Specific Overrides

Why This Works

Why the Documentation Repo?

What We’d Do Differently

The Meta Point

The Development Journey, Part 1: Nine Days from Zero

Day 1-2: The Foundation Sprint (Feb 8-10)

Day 3-4: The Data Layer (Feb 11-12)

Day 5: Authentication and API Wiring (Feb 13)

The First Render

What We Learned

Stats: Days 1-5 (Feb 8-13)

Code Written (as of Feb 13)

The Development Journey, Part 2: Making It Real

The City Grid Problem (Feb 14-15)

The Storm Cloud Saga

Building Placement and the Real Backend

The UI Overhaul (Feb 16)

Token Management

Observability

Stats: Days 6-9 (Feb 14-17)

Code Growth (Feb 14-17)

Feature Velocity

The Development Journey, Part 3: What We Learned

The Process Evolved

Workspace Boundaries

NuGet Versioning

PR Workflow

The “Open Source” Mistake

Debugging Patterns

CDK and AWS

Flutter Web

The Troop Training UI

Data-Driven Everything