Coding Agent

Coding Agent

Overview

Guidelines for performing autonomous coding tasks effectively and safely.

Before Coding

1. Understand the codebase

• Read package.json / pyproject.toml / Cargo.toml for project context
• Read README.md and any CLAUDE.md / AGENTS.md
• Identify the tech stack, patterns, and conventions in use
• Check existing tests to understand expected behavior

2. Plan before writing

• For non-trivial changes, outline the approach first
• Identify which files need to change
• Consider edge cases and error handling
• Check if similar patterns already exist in the codebase

3. Check the current state

git status        # Uncommitted changes?
git branch        # Which branch?
npm test          # Tests passing?

During Coding

Safety Rules

1. Never delete files without confirming with the user
2. Stage specific files — never git add -A or git add .
3. Run tests after changes — verify nothing is broken
4. Commit frequently — small, focused commits are better
5. Don't modify unrelated code — stay focused on the task

Code Quality

1. Follow existing conventions — match the project's style
2. Type safety — avoid any, use proper types
3. Error handling — handle failures at system boundaries
4. No dead code — remove unused imports, variables, functions
5. Minimal changes — don't refactor code you weren't asked to change

Multi-File Changes

1. Start with types/interfaces
2. Then implement core logic
3. Then update call sites
4. Then update tests
5. Finally update docs if needed

After Coding

Verification Checklist

npx tsc --noEmit          # TypeScript compiles
npm run lint               # No lint errors
npm test                   # All tests pass
git diff --stat            # Review changes

Commit

• Use Conventional Commits: feat:, fix:, refactor:, test:, docs:
• One logical change per commit
• Descriptive message explaining WHY, not just WHAT

Parallel Workflows

For multiple independent tasks, use git worktrees:

git worktree add ../project-fix-auth fix/auth-bug
git worktree add ../project-add-search feat/search
# Work in each directory independently
git worktree remove ../project-fix-auth  # Clean up after merge

Recovery

If something goes wrong:

git stash                  # Save current changes
git checkout .             # Discard all changes (careful!)
git stash pop              # Restore saved changes

Converted and distributed by TomeVault — claim your Tome and manage your conversions.