Workflow on Worlds of the Next Realm - Dev Blog

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.

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 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.