This document captures my experiences and learnings from using Claude Code (Anthropic's CLI tool) for software development. The goal is to share practical insights with the team on what works, what doesn't, and how to get the most out of AI-assisted development.
You can use AI agents to build prototypes/ideas rapidly. Some examples of what I've built:
- Chrome extension with PWA + local backend server for AI Assisted Test Automation
- macOS app for Localization OS and S3 Feature Config editing
- CLI tools for Xcode scripting
- iOS features
- Diagram; Flow Chart, Sequence Diagram, State Machine, Architecture Diagram, Dependency Graph
AI agents are tools that assist us, automating mundane tasks - but we as users must provide the vision, context, and knowledge to drive them effectively.
Think of it this way: You are the architect, AI is the construction crew. The AI can execute your blueprint quickly and efficiently, but it cannot design the building for you. The quality of the output directly reflects the quality of your input - your vision, your context, and your technical direction.
"I am free and that is why I am lost" — Franz Kafka
This quote captures the essence of AI agents and LLMs. They possess vast capabilities and can tackle almost any programming task you present to them - they are truly "free" in their potential. But this freedom comes with a critical limitation: without clear direction, strategy, and context from you, they become "lost," producing unfocused or suboptimal results. This is why being the architect isn't just a helpful metaphor - it's a fundamental requirement. You must establish the strategy, define the routine, shape the workflow, and maintain the mindset of active direction. The AI's freedom is only valuable when channeled by your vision and expertise.
AI agents represent the next step in the evolution of programming paradigm whether you like it or not:
Machine Code → Assembly → High-Level Languages → No-Code → Natural Language (AI)
| Generation | Abstraction | Accessibility | Productivity | Control vs Convenience | Deterministic | Examples |
|---|---|---|---|---|---|---|
| Machine Code | Lowest (binary) | Hardware engineers | Extremely slow | Full control, zero convenience | 100% | Raw binary (0s and 1s) |
| Assembly | Very low (mnemonics) | System programmers | Very slow | High control, minimal convenience | 100% | x86, ARM |
| High-Level Languages | Medium-high | Software developers | Fast | Balanced trade-off | 100% | Golang, Kotlin, Swift, Smalltalk, Cobol, Fortran |
| No-Code | Very high (visual) | Business users, non-developers | Very fast | Low control, high convenience | 100% | Ops Portal / MMT, Wix Website Builder |
| Natural Language (AI) | Highest (plain language) | Anyone | Extremely fast* | Variable control, max convenience | Non-deterministic | Claude Code, Codex, Copilot, Gemini Code Assist |
*Productivity depends heavily on the user's ability to provide clear direction, context, and strategy.
Just as high-level languages abstracted away assembly complexity, AI agents abstract away boilerplate and repetitive coding tasks. But just as you still need to understand programming concepts to use high-level languages effectively, you need software engineering knowledge to guide AI effectively. The critical difference: AI is non-deterministic - the same prompt can yield different results, which is why establishing clear workflows, strategies, and verification processes is essential.
- Twitter/X, all the influencers in the AI fields post and shares frequently on this platform such as configuration tips, new features/setup, tooling, thoughts.
- Disclaimer!, Twitter/X can be as toxic as Reddit if not more.
- @levelsio (Solo Techpreneur); Rapid prototyping new tech ventures (~100) (before AI Agent was a thing), guest speakers in a lot of tech event. Popularize Vibe Coding trend and hosted a few Vibe Coding events to build games at the beginning of it. His contents are generally troll / ai slope but fun to read once in a while.
- @steipete (Cofounder/ex CEO of PSPDFKit); got out of retirement to ship stuff with agentic AI coding
- @twannl (SwiftLee) Long time Swift Tech blogger; and have been sharing tips and his journey and setup using agentic AI coding
- @dimillian (Staff iOS Engineer in Medium); Sharing open soured macOS AI tooling that he built, thoughts & setup on agentic AI coding
- @GergelyOrosz (@Pragmatic_Eng); Sharing insights/news on tech in general but do covers AI topics too. Interviewed with some retired pioneer Software Engineers to get out of retirement to build new ideas because agentic AI coding enables them to leverage their domain knowledge with minimal commitment to learn new language/tooling.
| Area | Description |
|---|---|
| Code Exploration | Navigate large codebases, find implementations, trace dependencies, understand patterns |
| Implementation Tasks | Write features with clear specs, fix bugs, generate boilerplate code |
| Refactoring | Rename/reorganize code, extract methods/classes, apply consistent patterns |
| Visual Documentation | ASCII diagrams, flowcharts, architecture visualizations, state machines |
| Greenfield Development | Excels at creating code from zero with no existing constraints |
| Challenge | Description | Mitigation |
|---|---|---|
| Context Limits | Loses track during larger tasks, forgets earlier decisions | Break into smaller, focused sessions |
| Over-engineering | Adds unnecessary abstractions, does more than asked | Be explicit about scope; say what NOT to do |
| Accuracy Issues | Hallucinated APIs, incorrect assumptions, outdated patterns | Always review generated code |
| Garbage In, Garbage Out | Output quality depends entirely on input quality | Invest time in clear, detailed prompts |
| Overly Optimistic | Claims everything is possible, glosses over challenges | Challenge with "how exactly would you do this?" |
| Existing Codebases | Harder than greenfield; requires understanding constraints | Provide more context, plan iteratively |
| AI Fatigue | Generates too much code too fast, exhausting to review | Work in smaller increments, review as you go |
| Naive Networking | WebSocket implementations lack batching; updates sent live instead of throttled, can congest network | Request throttling/debouncing/backoff/circuit breaker upfront; specify update intervals |
| Unoptimized Complexity | Default implementations ignore space-time complexity; searching/grouping often O(n²) when O(n) possible | Ask for complexity analysis; suggest optimizations like memoization |
+------------------+ +------------------+ +------------------+
| Plan Mode |---->| Define Task |---->| Request Visuals |
| (start here) | | (clear context) | | (ASCII, states) |
+------------------+ +------------------+ +--------+---------+
|
v
+------------------+ +------------------+ +------------------+
| Refine |<----| Review |<----| Verify Details |
| (iterate as needed) | (manage AI fatigue) | (challenge optimism)
+--------+---------+ +------------------+ +------------------+
|
v
+------------------+ +------------------+
| Execute |---->| Done |
| (smaller chunks) | | |
+------------------+ +------------------+
Spend 30 minutes planning complex tasks before asking AI to implement.
Don't jump into coding immediately. Use the planning phase to:
- Clarify requirements
- Identify potential challenges
- Break down the task into steps
- Align on technical approach
Clear context regularly - reset at ~50% utilization for large tasks.
AI performance deteriorates as context fills up. Use the /clear command proactively to reset the conversation and start fresh. This is especially important when starting large or complex tasks. Don't wait until you hit the limit - clearing at around 50% utilization ensures the AI maintains optimal performance and doesn't lose track of important details.
Don't be afraid to discard ideas that aren't working.
Iterating with AI is fast - take advantage of this speed. If an idea becomes increasingly complex or difficult to implement, don't fall into the sunk cost fallacy of trying to salvage it. Instead, /clear the context and restart with a fresh approach. The ability to rapidly prototype and discard is one of AI's biggest advantages - use it freely.
Create scripts and apps for repeatable tasks instead of relying on AI.
AI agents produce non-deterministic output, which isn't ideal for routine or repeated operations. When you find yourself doing the same task multiple times, use AI to create deterministic tools: automation scripts, CLI utilities, or configuration generators. This reduces your reliance on AI for repetitive work and creates reliable, consistent results. Ironically, AI is excellent at building these deterministic tools for you.
Always start complex tasks in plan mode (/plan). Benefits:
- Forces you to think through the approach
- Allows iteration before code is written
- Easier to course-correct early
Spawn multiple agents concurrently for independent tasks to dramatically accelerate execution.
When tasks can be broken into independent units (data files, modules, features), spawn multiple agents in a single message to process them in parallel. This is especially powerful for analysis, validation, or implementation tasks without shared dependencies.
Example: Analyzing 39 locales sequentially would take ~78 minutes. By spawning 10 agents in 4 waves (10+10+10+9 locales), the task completed in ~8 minutes - a 10x speedup.
Key decisions:
- Can subtasks run independently? → Parallelize
- Do they share state or dependencies? → Serialize or partial parallelization
- Batch size: 5-10 items per agent balances parallelism with context limits
Common use cases: data processing, code reviews across modules, test suites, documentation generation, migrations.
Before implementing UI, ask for ASCII mockups:
+------------------+
| Header Bar |
+------------------+
| |
| Content Area |
| |
+------------------+
| [Button] |
+------------------+
This ensures alignment on UI/UX before any code is written.
For complex logic, ask the AI to create:
- State machine diagrams
- Truth tables for conditions
- Permutation tables for all scenarios
State Machine Example (Login Flow):
+-------------+
| Idle |
+------+------+
|
[tap login]
v
+-------------+
| Loading |
+------+------+
|
+--------------+--------------+
| |
[success] [failure]
v v
+-------------+ +-------------+
| Logged In | | Error |
+-------------+ +------+------+
|
[dismiss]
v
+-------------+
| Idle |
+-------------+
Permutation Table Example (Button State):
| isLoading | isEnabled | hasError | Button State |
|-----------|-----------|----------|-------------------|
| false | false | false | Disabled |
| false | false | true | Disabled + Error |
| false | true | false | Enabled |
| false | true | true | Enabled + Error |
| true | false | false | Loading |
| true | false | true | Loading |
| true | true | false | Loading |
| true | true | true | Loading |
This gives the AI (and you) better context for code paths and edge cases.
Plans are often high-level and lack substance on key technical details. Always:
- Ask "how specifically will this work?"
- Request concrete implementation details
- Drill down on integration points
When the AI says "we can easily do this," push back:
- "What are the potential challenges?"
- "What could go wrong?"
- "Walk me through the exact steps"
E.g.
- Building a remote Claude Agents manager using ttyd, how to attach to existing procesess, managing processes and etc. Rather complex and I lack the expertise to properly built one with that are usable and have the security aspects ironed out, better to pay a bit of money for battle tested commercial solution.
- iOS SDK + App to observe all data flow without code changes. There was some technical hurdles that cannot be resovled due to how Combine & Observable framework data flow but the AI agent would optimistically think it's doable without diving into the details, there are no library/framework atm that can achieve this with zero code.
For changes to existing code:
- Start with exploration - understand current state
- Plan incrementally - smaller steps
- Review each change before moving on
- Validate integration at each step
Your first prompt rarely produces the final result. Be prepared to:
- Clarify misunderstandings
- Add missing context
- Redirect when the AI goes off track
- Iterate multiple times
Create a CLAUDE.md file in your project root with:
- Project-specific context and conventions
- File organization guidance
- Coding standards to follow
- Common patterns in the codebase
The AI reads this file automatically and uses it to inform responses.
Configure hooks to automate validation:
- Pre-commit checks
- Linting validation
- Build verification
Extend capabilities with MCP (Model Context Protocol) servers:
- Browser automation for testing
- API integrations
- Custom tooling
Codified knowledge and workflows that the agent automatically picks up when relevant:
- Encode domain expertise and best practices
- Agent uses them automatically without manual invocation
- Standardize team approaches to common tasks
- Provide rich context upfront - The more the AI knows, the better it performs
- Iterate and clarify - Don't expect perfection on the first try
- Manage AI fatigue - Work in smaller, focused increments
- Verify everything - AI can be confidently wrong
- Know when to code manually - Sometimes it's faster to just do it yourself
- Challenge optimism - Push for concrete details
- Plan complex tasks - 30 minutes of planning saves hours of fixing
- Clear context regularly - Reset at ~50% utilization for large tasks
- Iterate rapidly - Don't fear discarding ideas that become too complex
- Build deterministic tools - Create scripts/apps for repeatable tasks
AI agents like Claude Code are powerful tools that can significantly accelerate development. But they are exactly that - tools. They amplify your capabilities; they don't replace your judgment.
Remember:
- You are the architect, AI is the construction crew
- The better your vision and context, the better the output
- AI assists with the "how," you provide the "what" and "why"
The developers who get the most value from AI tools are those who:
- Invest time in clear communication
- Maintain technical oversight
- Know when to use AI and when not to
- Treat AI output as a starting point, not the final answer
Start small, iterate often, and gradually expand how you use these tools in your workflow.