Designing tools without persistent state between invocations
Core Idea: Development tools should be stateless, with each invocation independent from others, to avoid the complexity and errors that arise from tracking changing state.
Key Elements
- Stateless tools have no persistent state between invocations
- Shell environments introduce problematic state, particularly working directory
- Advanced models like Sonnet 3.7 struggle with tracking current working directory
- Project configuration should minimize state dependencies
Implementation Strategies
- Structure projects so commands can run from a single directory
- Avoid tools that change state between invocations
- When state is necessary, continuously feed current state into the model
- Create wrapper tools that handle state transitions transparently
- Explicitly track and communicate state changes when unavoidable
Common Problems
- Working directory confusion in multi-component projects
- Environment variables that change tool behavior
- Session-based authentication that expires
- Configuration that accumulates or changes across invocations
- Distributed systems with eventual consistency
Connections
- Related Concepts: Mise en Place (proper environment setup), Know Your Limits (understanding model capabilities)
- Broader Context: Functional Programming Principles (avoiding mutable state)
- Applications: Project Structure Best Practices (organizing code to minimize state)
References
- Edward Z. Yang (2025). "AI Blindspots" collection, March 2025.
#software-development #stateless-design #ai-development #tool-design
Connections:
Sources:
- From: AI Blindspots