docs: document Tasks API field visibility limitations (Gang Rui analysis)
Integration of community practitioner feedback on Tasks API (v2.1.16+) field visibility constraints discovered through real-world usage. Changes: - guide/ultimate-guide.md: * Added 3 rows to comparison table (field visibility, metadata, overhead) * New subsection "⚠️ Tasks API Limitations (Critical)" (~40 lines) * Field visibility constraint table, cost examples, 3 workaround patterns - guide/workflows/task-management.md: * New subsection "⚠️ Field Visibility Limitations" (~35 lines) * Workflow adjustments, cost awareness, mitigation strategies - guide/cheatsheet.md: * Added limitation note with actionable tip (~3 lines) - machine-readable/reference.yaml: * 4 new entries: limitations, field_visibility, cost_overhead, workarounds * Updated resource_evaluations_count: 16 → 22 - docs/resource-evaluations/016-gang-rui-tasks-api-limitations.md: * New comprehensive evaluation (score 5/5 CRITICAL) * Fact-check, challenge phase, integration details - README.md: * Updated resource evaluations count: 15 → 22 assessments Score: 5/5 (CRITICAL) - Breaks recommended workflow, 11x-51x cost overhead, prevents user frustration, maintains guide credibility. Source: https://www.linkedin.com/posts/limgangrui_i-explored-the-new-claude-codes-task-system-activity-7420651412881268736-Hpd6 Date: 2026-01-24 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
edf74b38c5
commit
3a5012eef7
7 changed files with 493 additions and 10 deletions
|
|
@ -3137,6 +3137,9 @@ Claude Code provides two task management approaches:
|
|||
| **Dependencies** | ❌ Manual ordering | ✅ Task blocking (A blocks B) |
|
||||
| **Coordination** | Single agent | ✅ Multi-agent broadcast |
|
||||
| **Status tracking** | pending/in_progress/completed | pending/in_progress/completed/failed |
|
||||
| **Description visibility** | ✅ Always visible | ⚠️ TaskGet only (not in TaskList) |
|
||||
| **Metadata visibility** | N/A | ❌ Never visible in outputs |
|
||||
| **Multi-call overhead** | None | ⚠️ 1 + N calls for N full tasks |
|
||||
| **Enabled by** | Always available | Default since v2.1.19 |
|
||||
|
||||
#### Tasks API (v2.1.16+)
|
||||
|
|
@ -3191,6 +3194,47 @@ claude
|
|||
- Multi-agent coordination scenarios
|
||||
- Need to resume work after context compaction
|
||||
|
||||
**⚠️ Tasks API Limitations (Critical)**
|
||||
|
||||
**Field visibility constraint**:
|
||||
|
||||
| Tool | Visible Fields | Hidden Fields |
|
||||
|------|----------------|---------------|
|
||||
| `TaskList` | `id`, `subject`, `status`, `owner`, `blockedBy` | `description`, `activeForm`, `metadata` |
|
||||
| `TaskGet` | All fields | - |
|
||||
|
||||
**Impact**:
|
||||
- **Multi-call overhead**: Reviewing 10 task descriptions = 1 TaskList + 10 TaskGet calls (11x overhead)
|
||||
- **No metadata scanning**: Cannot filter/sort by custom fields (priority, estimates, tags) without fetching all tasks individually
|
||||
- **Session resumption friction**: Cannot glance at all task notes to decide where to resume
|
||||
|
||||
**Cost example**:
|
||||
```bash
|
||||
# Inefficient (if you need descriptions)
|
||||
TaskList # Returns 10 tasks (no descriptions)
|
||||
TaskGet(task-1), TaskGet(task-2), ..., TaskGet(task-10) # 10 additional calls
|
||||
|
||||
# Total: 11 API calls to review 10 tasks
|
||||
```
|
||||
|
||||
**Workaround patterns**:
|
||||
|
||||
1. **Hybrid approach** (Recommended):
|
||||
- Use Tasks API for **status tracking** and **dependency coordination**
|
||||
- Maintain markdown files in repo for **detailed implementation plans**
|
||||
- Example: `docs/plans/auth-refactor.md` + Tasks for status
|
||||
|
||||
2. **Subject-as-summary pattern**:
|
||||
- Store critical info in `subject` field (always visible in TaskList)
|
||||
- Keep `description` for deep context (fetch on-demand with TaskGet)
|
||||
- Example subjects: `"[P0] Fix login bug (src/auth.ts:45)"` vs `"Fix bug"`
|
||||
|
||||
3. **Selective fetching**:
|
||||
- Use TaskList to identify tasks needing attention (status, blockedBy)
|
||||
- Only call TaskGet for tasks you're actively working on
|
||||
|
||||
**Source**: Community practitioner feedback ([Gang Rui, Jan 2026](https://www.linkedin.com/posts/limgangrui_i-explored-the-new-claude-codes-task-system-activity-7420651412881268736-Hpd6))
|
||||
|
||||
#### TodoWrite (Legacy)
|
||||
|
||||
**Tool**: `TodoWrite` - Creates task lists stored in session memory
|
||||
|
|
@ -14763,6 +14807,29 @@ SuperClaude transforms Claude Code into a structured development platform throug
|
|||
- Task management and session persistence
|
||||
- **Behavioral modes** for optimized workflows
|
||||
|
||||
#### Production Config Collections
|
||||
|
||||
For **battle-tested, ready-to-use configurations** from production environments:
|
||||
|
||||
| Repository | Author | Stats | Focus |
|
||||
|------------|--------|-------|-------|
|
||||
| [**everything-claude-code**](https://github.com/affaan-m/everything-claude-code) | Affaan Mustafa (Anthropic hackathon winner) | ⭐ 31.9k | Production configs from 10+ months intensive use |
|
||||
|
||||
**Why this matters**: This is the **largest community-validated Claude Code resource** (31.9k stars in 9 days). Unlike tutorials, these are **configs proven in production** through winning Anthropic's hackathon (Zenith project).
|
||||
|
||||
**Unique innovations not found elsewhere**:
|
||||
- **mgrep**: 50% token reduction vs standard grep/ripgrep
|
||||
- **hookify**: Conversational hook creation (describe need → JSON generated)
|
||||
- **pass@k metrics**: Formal verification approach (k=3 → 91% success rate)
|
||||
- **Sandboxed subagents**: Tool restrictions per agent (security-reviewer can't Edit files)
|
||||
- **Plugin ecosystem**: One-command installation for all configs
|
||||
|
||||
**Positioning**: Complementary to this guide—we teach concepts ("why"), they provide production configs ("how").
|
||||
|
||||
**See also**: [Comprehensive evaluation](../docs/resource-evaluations/015-everything-claude-code-github-repo.md) (Score 5/5)
|
||||
|
||||
---
|
||||
|
||||
#### SuperClaude Behavioral Modes
|
||||
|
||||
> ⚠️ **Non-official Extension**: SuperClaude flags (`--learn`, `--uc`, `--think`, etc.) are **NOT Claude Code CLI flags**. They work via prompt injection in CLAUDE.md files and require installing the SuperClaude framework.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue