> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Best Practices for AI Agents
> Guidelines for AI agents using the sudocode MCP server
This page contains best practices specifically for AI agents using the sudocode MCP server. These guidelines help agents work effectively with the sudocode workflow. Feel free to read them to understand how agents typically use sudocode!
## Work Selection
* **Always check `ready()` first** - Don't claim work that's blocked or in progress
* **Review `show_issue()` before claiming** - Understand full context and requirements
* **Prioritize by priority field** - Work on P0 issues before lower priority
* **Prefer foundation work** - Unblock other work by completing blockers first
## Status Management
* **Claim immediately** - Set `status: in_progress` when starting work
* **Close with documentation** - Update description with summary of work completed
* **Mark blocked promptly** - Don't leave blocked work in `in_progress` state
* **Create blockers early** - Discover and document blockers as soon as possible
## Feedback and Communication
* **Provide feedback early** - Don't wait until completion to report ambiguities
* **Use appropriate feedback types**:
* `request` - When you need clarification or decisions
* `suggestion` - When you have improvement ideas
* `comment` - For observations or context
* **Anchor feedback to lines** - Use `line` parameter for precise feedback
* **Continue with reasonable assumptions** - Don't block on feedback, proceed intelligently
## Relationship Management
* **Link issues to specs** - Use `implements` relationship
* **Model dependencies** - Use `blocks` for hard blockers
* **Document discovery** - Use `discovered-from` when finding new work
* **Cross-reference liberally** - Use `[[ID]]` syntax in descriptions
## Multi-Agent Coordination
* **Check ready() frequently** - Status changes as others work
* **Update status promptly** - Keep status current so others know what's available
* **Create specific issues** - Break down work into claimable units
* **Communicate through issues** - Use issue descriptions to coordinate
## Error Handling
When tool calls fail:
**Issue not found:**
```
Error: Issue ISSUE-999 not found
```
→ Verify ID spelling, check if issue was deleted
**Status transition invalid:**
```
Error: Cannot transition from closed to in_progress
```
→ Use correct status workflow: open → in\_progress → closed
**Missing required fields:**
```
Error: title is required for creating issues
```
→ Always provide required fields (title, content) when creating
**Relationship already exists:**
```
Error: Relationship already exists
```
→ No action needed, relationship is already recorded
**Circular dependency:**
```
Error: Would create circular dependency
```
→ Restructure dependencies to avoid cycles
## Tool Usage Patterns
### Common Combinations
**Finding and claiming work:**
```
1. ready() → Get available issues
2. show_issue() → Understand requirements
3. upsert_issue(status: in_progress) → Claim issue
```
**Creating implementation plan:**
```
1. show_spec() → Review specification
2. upsert_issue() × N → Create issues
3. link(implements) × N → Link to spec
4. link(blocks) × M → Model dependencies
```
**Providing feedback:**
```
1. show_spec() → Read spec content
2. add_feedback() → Anchor feedback
3. Continue with work...
```
**Investigating blockers:**
```
1. ready() → Check for work
2. list_issues(status: blocked) → Find blocked issues
3. show_issue() → See what's blocking
4. show_issue() → Check blocker status
5. upsert_issue(blocker, status: in_progress) → Work on blocker
```
**Completing work:**
```
1. upsert_issue(status: closed, description: ...) → Close with summary
2. Link discovered issues if any → link(discovered-from)
3. Add feedback to specs if needed → add_feedback()
```
### When to Use Each Tool
**ready**
* Starting a work session
* After completing an issue (to find next work)
* When checking what's available to claim
* Before multi-agent coordination
**list\_issues**
* Filtering by status, priority, tags
* Finding blocked work
* Searching for specific issues
* Getting overview of project state
**show\_issue**
* Before claiming work (understand context)
* Investigating relationships
* Checking feedback on issue
* Understanding why issue is blocked
**upsert\_issue**
* Creating new issues from specs
* Claiming work (status → in\_progress)
* Completing work (status → closed)
* Updating issue details
* Marking as blocked
**list\_specs**
* Finding relevant specifications
* Searching for spec topics
* Getting project overview
**show\_spec**
* Before implementing spec
* Before creating implementation plan
* Before providing feedback
* Understanding requirements
**upsert\_spec**
* Creating research documentation
* Documenting architecture
* Recording decisions
* Creating feature specifications
**link**
* Connecting issues to specs (implements)
* Modeling blockers (blocks)
* Recording dependencies (depends-on)
* Tracking discovery (discovered-from)
* Cross-referencing (references, related)
**add\_reference**
* Adding cross-references to existing content
* Linking related work
* Creating navigation between entities
**add\_feedback**
* Requesting clarifications (type: request)
* Suggesting improvements (type: suggestion)
* Adding observations (type: comment)
* Anchoring to specific lines
## Related Documentation
Practical examples of AI agents using sudocode
Setup and tool reference
Command-line equivalents