chore: snapshot main sync

docs/how-to-build-a-coding-agent/AGENT.md

@@ -0,0 +1,74 @@
+# Agent Instructions
+
+## Development Environment
+This project uses [devenv](https://devenv.sh/) for reproducible development environments with Nix.
+
+## Commands
+- `devenv shell` - Enter the development shell
+- `devenv test` - Run tests (currently runs git version check)
+- `go build` - Build Go project
+- `go run main.go` - Run the chat application
+- `go test ./...` - Run all Go tests
+- `go test <package>` - Run tests for specific package
+- `go mod tidy` - Download dependencies
+- `hello` - Custom script that greets from the development environment
+
+### Application Commands
+- `go run chat.go` - Simple chat interface with Claude
+- `go run read.go` - Chat with file reading capabilities
+- `go run list_files.go` - Chat with file listing and reading capabilities
+- `go run bash_tool.go` - Chat with file operations and bash command execution
+- `go run edit_tool.go` - Chat with full file operations (read, list, edit, bash)
+
+### Verbose Logging
+All Go applications support a `--verbose` flag for detailed execution logging:
+- `go run chat.go --verbose` - Enable verbose logging for debugging
+- `go run read.go --verbose` - See detailed tool execution and API calls
+- `go run edit_tool.go --verbose` - Debug file operations and tool usage
+
+## Architecture
+- **Environment**: Nix-based development environment using devenv
+- **Shell**: Includes Git, Go toolchain, and custom greeting script
+- **Structure**: Chat application with terminal interface to Claude via Anthropic API
+
+## Code Style Guidelines
+- Follow Nix conventions for devenv.nix configuration
+- Use standard Git workflows
+- Development environment configuration should be reproducible
+
+## Troubleshooting
+
+### Verbose Logging
+When debugging issues with the chat applications, use the `--verbose` flag to get detailed execution logs:
+
+```bash
+go run edit_tool.go --verbose
+```
+
+**What verbose logging shows:**
+- API calls to Claude (model, timing, success/failure)
+- Tool execution details (which tools are called, input parameters, results)
+- File operations (reading, writing, listing files with sizes/counts)
+- Bash command execution (commands run, output, errors)
+- Conversation flow (message processing, content blocks)
+- Error details with stack traces
+
+**Log output locations:**
+- **Verbose mode**: Detailed logs go to stderr with timestamps and file locations
+- **Normal mode**: Only essential output goes to stdout
+
+**Common troubleshooting scenarios:**
+- **API failures**: Check verbose logs for authentication errors or rate limits
+- **Tool failures**: See exactly which tool failed and why (file not found, permission errors)
+- **Unexpected responses**: View full conversation flow and Claude's reasoning
+- **Performance issues**: See API call timing and response sizes
+
+### Environment Issues
+- Ensure `ANTHROPIC_API_KEY` environment variable is set
+- Run `devenv shell` to ensure proper development environment
+- Use `go mod tidy` to ensure dependencies are installed
+
+## Notes
+- Requires ANTHROPIC_API_KEY environment variable to be set
+- Chat application provides a simple terminal interface to Claude
+- Use ctrl-c to quit the chat session