June 23 to June 27, 2025
I am starting this series roughly three weeks into an ambitious development project. Over time I will backfill some of the “how did we get here” context but for now I’d like to start with something of a pro tip I learned the hard way.
So here’s what happened: I was drowning in context switches with my AI collaborator. Every morning felt like that scene in Memento where I’m trying to piece together what the hell we built yesterday from cryptic git commits and half-finished tests.
You know the drill. The AI can write code faster than you can review it, but ask it about that clever error handling pattern you implemented Tuesday? Blank stare. (OK, not literally, but you know what I mean.)
A week or so ago, about a month into this project, I started keeping session logs. Or rather, I started asking whichever model I was talking to to maintain a log for me.
What began as desperate self-preservation has become something genuinely useful — not revolutionary, not game-changing, just… useful. Here’s what’s working for me.
When AI Acceleration Meets Human Navigation
Working with AI on complex architecture is like asking a very very clever dog to drive your car. Sure, it’s powerful, but power without direction is just expensive chaos.
Case in point: During our file analysis integration, we spent hours debugging what we thought was an async pattern issue in our tests. Generated test after test, each more sophisticated than the last. The AI was incredibly helpful, cranking out different approaches, suggesting new patterns…
Then I actually shared the specific error message: “FastAPI version mismatch.”
facepalm
Neither of us had stopped to ask if we were solving the right problem. We were so busy being productive that we forgot to be effective. (If this sounds familiar, it’s because we’ve all been here before — remember when everyone was going to revolutionize everything with microservices? Yeah, that worked out great for everyone’s complexity budget.)
Session Logs: More Than Meeting Notes
I’m not reinventing the wheel here. People have been keeping dev journals and decision logs since the 1970s. What’s different is how these logs work specifically for AI collaboration.
A session log isn’t your typical “Action items: Bob to follow up on widget procurement” situation. It’s a structured capture of:
- Why we made specific architectural decisions (and which alternatives we rejected)
- What actually worked versus what we thought would work
- The anti-patterns we discovered (usually the hard way)
- Context that would be impossible to reconstruct from code alone
Here’s what actually goes in one:
# PM-011 File Analysis Integration Session Log - June 27, 2025
**Project**: Piper Morgan - AI PM Assistant
**Branch**: pm-011-file-analysis-integration
**Previous Session**: June 26 (Phases 1-2 complete)
## Objective
Fix DocumentAnalyzer contract violation, proceed to Phase 3 (E2E testing)
## Progress
- ✅ Root cause: DocumentAnalyzer throwing exceptions instead of
returning AnalysisResult with error metadata
- 🔄 [DISCOVERED] WorkflowFactory not creating tasks for analyze_file
- 🚨 [ANTI-PATTERN] Discovering design through test failuresNothing magical. Just writing stuff down in a way that future-me (or future-Claude) can actually use.
The Good, The Bad, and The “Wait, We Have Two of Those?”
The real value emerges when you track both successes and failures systematically. Not because it’s revolutionary — engineers have been doing post-mortems since the early 1950s — but because AI collaboration introduces new failure modes.
Anti-Pattern Collection (Greatest Hits)
❌ Assuming method names without checking (validate vs validate_file_path)
❌ Modifying domain models to make tests pass (rookie move)
❌ Writing tests before understanding existing patterns
❌ Using test failures as primary design feedback
Architectural Archaeology
My favorite discovery from the logs:
DUPLICATE ARCHITECTURE DISCOVERED:
WorkflowExecutor: Legacy code from initial GitHub integration
OrchestrationEngine: The actual task-based architecture
Revelation: We’ve been maintaining two parallel systems
You only find these gems when you’re deep in integration work, trying to figure out why your beautiful clean architecture is behaving like it has multiple personality disorder. (This is exactly the kind of thing that happens when you’re moving fast — not unique to AI development, just amplified by it.)
The Human-AI Tag Team Dynamic
After dozens of sessions, here’s the pattern that emerged:
Human (that’s me):
- Sets strategic direction (“We’re implementing CQRS-lite, not full event sourcing”)
- Enforces quality standards (“No, we don’t modify domain models for tests”)
- Recognizes when to stop digging and start thinking
- Maintains architectural coherence across sessions
AI (that’s Claude):
- Executes systematically with verification
- Finds patterns across large codebases
- Generates comprehensive test coverage
- Never gets tired of refactoring
Think of it less like pair programming and more like working with an eager but literal junior developer. Incredibly capable, needs clear guardrails.
Logs as Institutional Memory
Here’s something that actually surprised me: These logs become training data. Start a new session, provide the relevant logs, and your AI collaborator has context:
CRITICAL FOR FUTURE SESSIONS Always provide latest models.py at session start. Domain models = contract. Everything else follows.
Again, this isn’t revolutionary — it’s just applying basic documentation practices to a new context. But it works. Same reason bands record their shows and listen back to them to try to improve how they play.
The Sustainability Paradox
Here’s the thing nobody tells you about AI-accelerated development: It makes sustainable practices more important, not less.
When I was leading product at a raw early-stage mental health startup, we learned that speed without sustainability just means you hit the wall faster. Same principle here, just with different tools.
When you can generate a week’s worth of code in an afternoon, you can also generate a month’s worth of technical debt. The session logs become your guardrails:
- Decision checkpoints preventing architectural drift
- Anti-pattern documentation stopping repeated mistakes
- Natural break points for reflection and course correction
- Accumulating wisdom rather than just accumulating code
Not magic. Just discipline.
OK, But Why Should You Care?
Because I’m learning something useful here. Having to explain architectural decisions clearly enough for an AI to understand and follow is making me a better architect. Not revolutionarily better — just incrementally, measurably better.
When you write “We chose pattern X over pattern Y because…” you can’t hide behind hand-waving. When you document an anti-pattern, you’re forced to understand why it’s an anti-pattern. When you explicitly state your assumptions, you start seeing which ones are garbage.
It’s not unlike the way when you are explaining a concept to a colleague or teaching or mentoring someone, you find your own understanding enriched by your work at articulating it clearly and by whatever sort of feedback, reaction, or questions you get back. Just in this case, your student has vast (though fallible) memory and implements exactly what you said (not what you meant), as best as it can make out.
How to Actually Do This
Start small. Don’t try to capture everything. Focus on:
- Today’s objective (one sentence)
- Key decisions and why
- What went wrong and what you learned
- Tomorrow’s starting point
Use a template. Consistency matters:
- Session metadata (date, branch, previous session)
- Objectives and progress checkpoints
- Architectural decisions and rationale
- Issues and anti-patterns discovered
- Next steps and context needs
Review before starting. Every session begins with 2 minutes reading yesterday’s log. This investment pays off within the first 10 minutes, guaranteed. (Or your money back. Wait, this is free. Never mind.)
Make it sustainable. If it feels like a chore, you’re doing too much. Better to capture three critical decisions than attempt a transcript.
What’s Actually Different Here
What’s different with AI collaboration is the velocity of decision-making and the cost of context loss.
Traditional softwaer work: Make a decision, implement it over days/weeks, see results, adjust. AI-assisted dev work: Make 50 decisions in an afternoon, implement them all, debug the interactions.
The session log is a tool that fits this new velocity. Like switching from email to Slack when your team’s communication speed increased. Same human needs, different tooling.
The Bottom Line
Into the second week of this practice, session logs have made our AI collaboration more effective. Not transformed, not revolutionized — just more effective. They’re a thinking tool that happens to work well for this particular flavor of development.
The compound effect is real but modest. Each session builds on documented learnings rather than rediscovered mistakes. Complex architectural patterns stay coherent across weeks of development. And that AI collaborator who starts each session with zero context? Now it starts with exactly the context that matters.
This also means that when I want to, well, write a blog post about what we’ve been working on, I can review the session logs since the last blog post and look for interesting moments and themes to address.
I’ve started using session logs even outside of my tech-oriented chats, so I have a feeling this practice has got legs, at least for me.
Next time you find yourself explaining the same architectural decision for the third time, ask yourself: “What would happen if I wrote this down once and never had to explain it again?”