Writing Code With Ai
At my previous employer we were strongly encouraged to learn and use Claude Code, and I’m continuing to do so for this project to practice those particular skills. I have some practices I use when doing so that came more from experimentation than any advice or documentation anywhere. So I thought I might as well write some of my thoughts down.
Philosophy
First of all, while AI is great at writing a lot of code quickly, it also has some limitations we should be aware of. I think it’s important to understand those limitations and make sure you’re only using AI where it really adds value. Otherwise, all you’re doing is changing how you work rather than actually increasing your rate of completion, and what’s the point of that?
AI is great at rapid prototyping, which is exactly where this project is at, so I’m using it a bit more heavily right now. That said, one thing I tell all my engineers is:
Remember that when you check into source control, your name is on that code. You had better understand it and be ready to explain how it works and maintain it over time.
Planning
There’s probably plenty already written on how to set up your CLAUDE.md, or AGENTS.md if you’re using GPT Codex, Cursor, Copilot, etc. Actually my habit is to just ln -s AGENTS.md CLAUDE.md so I have one file to maintain across tools. High level architecture and coding style go in here nicely, but I also usually separate out a game-design-doc.md to check into source control as well.
Then I also maintain a folder of feature plan docs. In fact, I have a section in CLAUDE.md about how to write these which maybe does a better job explaining them than what I was just about to write:
### Feature Development Methodology
All new features should be planned and implemented using an **incremental, phase-by-phase approach** that delivers complete, testable functionality at each stage.
#### Core Principles
1. **Integrated Full-Stack Phases** - Each phase must integrate both backend AND frontend work together. Never separate "all backend first, then frontend later."
2. **Runnable State After Each Phase** - The project must remain in a deployable, non-broken state after completing each phase. No "work-in-progress" code that breaks existing features.
3. **Digestible Scope** - Keep each phase focused and manageable (~10-20 files per phase). Break large features into logical increments.
4. **Testable Deliverables** - Every phase must include specific testable outcomes. Tests must be performable by a human reviewer interacting with the running game — not by inspecting database records, calling raw REST endpoints, or reading server logs. If verifying a phase requires a developer tool rather than gameplay, that is a sign the phase is incomplete and needs more frontend work before it qualifies as a deliverable.
5. **Review Checkpoints** - Get approval before proceeding to the next phase. Allow time for course corrections.
#### Feature Plan Requirements
When creating a feature plan document (in `docs/feature-plans/`), include:
1. **Implementation Approach Section** (at the top) - List all phases with brief descriptions, explain principles being followed, provide instructions on how to use the plan.
2. **For Each Phase, Document:**
- **Goal**: What does this phase accomplish?
- **Backend Work**: Specific files, services, endpoints, models to create/modify.
- **Frontend Work**: Specific components, services, stores, UI elements to create/modify.
- **Deliverable**: What working functionality will exist after this phase?
- **Testing**: Specific test scenarios to verify the phase is complete.
3. **Supporting Details** (after phase breakdown) - Architecture overview, database schemas, API endpoint specs, code examples, security considerations.
4. **Checklists**
- Each phase should include task checklists with checkboxes that the implementor checks off as they complete tasks.
- Each phase should also include a list of testable outcomes with checkboxes for the human tester to check when reviewing phase completion.
- **Important**: When implementing a phase, check off completed task checkboxes as you go. **Never** check off Testing/testable outcome checkboxes — those are reserved for the human reviewer to verify.
#### Implementation Workflow
1. **Plan Review**: Review the complete feature plan before starting any implementation.
2. **Phase-by-Phase Implementation**: Implement one complete phase (backend + frontend), review and validate, get approval before proceeding.
3. **Iteration**: If issues are found, address them before moving to the next phase.
4. **Completion**: All phases complete = feature is done and tested.
I check these plans into source control. That helps us track implementation progress over time, allows us to look at diffs when want to tune the plan, and leaves a lovely artifact on how the code was built for later use (both by us humans, and AI if its tasked with fixing or extending an existing system).
There are a couple of specific strategies at play in the above that are worth digging into:
Phased Implementation
Breaking down work into smaller chunks should be very familiar standard practice to any game engineer. So why would you not expect AI to follow the same pattern? Doing it this way has the following effects:
- Keeps the AI on track by having logical pause points.
- Makes each section digestable, that is, not too difficult for the human to read and review the code.
- Gives us natural points to evaluate our progress and discover if and when a pivot from the original plan is necessary.
That third one is actually really important. I’ve had a couple cases where I didn’t discover a flaw in the plan until we were halfway through implementation. That’s fine - I talked to the AI, discussed how we would pivot, asked it to adjust the code and the plan. Then we checked in the plan and moved on.
Sometimes the pivot is so big it warrants creating a separate plan to execute the pivot, then come back to the original plan to update and move forward – or not, maybe you just drop it at that point and go forward like a shark!
Exclusion of Code
You’ll notice some language around goals, files to modify, etc. In early stages of developing this technique I found the AI would often include all the code it wanted to write in the plan. That’s not helpful, what’s the point of the plan then?!
If you find the AI doing this you may have to nudge it to stop doing that. The point of the plan is to describe what our goals are and how we’re going to achieve them at a high level, not write every line of code. A highly specific recipe of execution like that is way too brittle.
Use of Checkboxes
This feels so silly, but markdown has a syntax for checkboxes both unchecked and checked. Making AI create this kind of forces it to stay on the rails. It must check off each box as it goes, and if it misses anything it’s self-correcting.
I also like them for testing. I will check off the boxes that succeed, and I can just tell the AI “Hey, the tests that did not get check marks have failed, please investigate.” And the whole thing can be checked back into source control at any stage and act as full context to start a new session with AI later as needed.
Example
OK, there’s already way too much text in this post, so I’ll just include it as a link. Here’s a full example of the executed Equipment Plan I created and used for implementing that system in this game. You’ll note it has a number at the front - I number every plan so they will always be organized in chronological order of execution.