Skip to content

Agent Workflow Best Practices

This guide covers patterns and anti-patterns for effective long-running AI coding sessions.

Core Philosophy

Each AI agent session starts fresh. Without structured handoffs, agents:

  • Lose context from previous work
  • Repeat completed tasks
  • Declare "victory" prematurely
  • Leave code in broken states

Klondike provides the structure to maintain coherence across sessions.

Session Lifecycle

Starting a Session

Before doing any coding work:

# 1. Check project status
klondike status

# 2. Validate artifacts
klondike validate

# 3. Review recent changes
git log --oneline -10

# 4. Start the session
klondike session start --focus "F001 - Feature description"

# 5. Run any init scripts
./init.sh  # or init.ps1

# 6. Mark feature in progress
klondike feature start F001

During a Session

  1. Focus on ONE feature at a time
  2. Commit after each meaningful change
  3. Test as you go, not at the end
  4. If blocked, mark it and move on

Ending a Session

# 1. Ensure code compiles/passes linting
npm run lint  # or equivalent

# 2. Commit all changes
git add .
git commit -m "feat(auth): complete login form"

# 3. Verify completed features
klondike feature verify F001 --evidence "tests/login.test.js"

# 4. End session with handoff notes
klondike session end \
  --summary "Completed login form" \
  --next "Add password reset"

Prohibited Behaviors

Never Do These

❌ Don't Why
One-shot complex features Break into small, verifiable steps
Declare "complete" without testing Use feature verify with evidence
Manually edit .klondike/*.json Use CLI commands
Leave code broken at session end Always leave in mergeable state
Skip commits Commit early and often
Batch testing to the end Test incrementally
Commit without running builds Always verify before commit

Pre-Commit Verification

Before every commit, run these checks:

1. Detect Project Stack

Stack How to Detect
Python (uv) pyproject.toml with [tool.uv]
Python (pip) requirements.txt or setup.py
Node.js package.json
Rust Cargo.toml
Go go.mod

2. Run Appropriate Commands

Check Python (uv) Node.js Rust
Lint uv run ruff check npm run lint cargo clippy
Format uv run ruff format --check npm run format cargo fmt --check
Test uv run pytest npm test cargo test
Build N/A npm run build cargo build

3. Record Results

Document each check before committing:

#### Pre-Commit Verification
| Command | Exit Code | Notes |
|---------|-----------|-------|
| npm run lint | 0 | ✅ |
| npm test | 0 | ✅ 42 tests passed |
| npm run build | 0 | ✅ |

Git Hygiene

Commit Messages

Use conventional commits:

<type>(<scope>): <short description>

<longer description if needed>

Types:

  • feat: New feature
  • fix: Bug fix
  • refactor: Code change (no feature/fix)
  • docs: Documentation only
  • test: Adding/updating tests
  • chore: Maintenance

Commit Frequency

✅ DO: Commit after completing a logical unit of work

❌ DON'T: Wait until "it's perfect"

Recovery Patterns

# Revert a bad commit
git revert <commit-hash>

# See all recent actions
git reflog

# Stash work in progress
git stash save "WIP: feature description"

Feature Granularity

Too Big (Split These)

  • "Implement user authentication"
  • "Build the frontend"
  • "Add database integration"

Just Right

  • "User can log in with email/password"
  • "Display loading spinner during API calls"
  • "Add form validation for signup"

Too Small (Combine)

  • "Add a button"
  • "Change color to blue"
  • "Fix typo"

Testing Standards

Test features as a user would:

Application Type Testing Approach
Web Apps Browser automation, screenshots
APIs Test actual endpoints, not mocks
CLI Tools Run real commands, check output
Libraries Unit tests with real implementations

Verification Evidence

When verifying features, provide concrete evidence:

klondike feature verify F001 \
  --evidence "tests/login.test.js:42-87 - all 5 tests pass"

Context Bridging

The agent-progress.md file bridges context between sessions:

## Session 5 Summary

### Focus
F003 - Password reset flow

### Completed
- Reset email template
- Token generation
- Password update endpoint

### Next Steps
1. Add email rate limiting
2. Implement token expiry
3. Add confirmation UI

### Blockers
- Email service rate limits TBD

Each new session should:

  1. Read the progress file
  2. Understand what was done
  3. Pick up the next steps
  4. Continue the work

Anti-Patterns

Victory Declaration

# ❌ BAD
klondike feature verify F001  # No evidence!

# ✅ GOOD
klondike feature verify F001 --evidence "tests/auth.test.js passing"

Breaking Changes at Session End

# ❌ BAD
git commit -m "WIP: broken state"
klondike session end

# ✅ GOOD
git stash save "WIP: incomplete feature"
klondike feature block F001 --reason "Needs more time"
klondike session end --summary "Partially complete"

Ignoring Blockers

# ❌ BAD
# Just pretend the API works...

# ✅ GOOD
klondike feature block F003 --reason "API credentials pending"
klondike feature start F004  # Work on something else