[DOCS] Clarify official configuration paths for Agent Teams vs Subagents — what is auto-recognized vs user reference?

Problem

There is significant confusion about which configuration files are officially auto-recognized by Claude Code vs which are just reference documents that Claude reads as context. Even Claude Code itself gives inconsistent answers when asked about this.

Specifically, the following questions need clear documentation:

Questions

1. .claude/agents/*.md (Subagents)

• Is this directory auto-recognized by Claude Code at startup, or does Claude just read these files when referenced?
• Are these files for subagents only, or can they also be used for Agent Teams teammates?
• Per #24316 and #26107, these are currently NOT used by Agent Teams. Is this by design or planned for integration?

2. ~/.claude/teams/{team-name}/config.json (Agent Teams)

• This is auto-generated when a team is created via natural language. Confirmed.
• Can users manually edit this file to pre-configure teams, or is it strictly system-managed?

3. Project-level .claude/teams/teams.json (User-created)

• Some users create a teams.json in their project's .claude/teams/ directory to define team roles, scopes, and tech stacks.
• Is this officially recognized by Claude Code in any way, or does it only work because Claude reads it as a regular file during conversation?
• If it's NOT officially recognized, should it be? (It's very useful in practice for consistent team configurations.)

Why this matters

• Users are writing internal company documentation based on Claude's responses about these paths
• Claude Code itself gives different answers in different sessions about what is "official"
• The boundary between "auto-recognized config" and "reference document Claude happens to read" is unclear
• Related issues: #24316, #26107

Current understanding (please confirm or correct)

| Path | Type | Auto-recognized? | Purpose |
|------|------|-------------------|---------|
| .claude/agents/*.md | Subagent definition | Unclear | Define specialized subagents |
| ~/.claude/teams/*/config.json | Team config | Yes (auto-generated) | System-managed team state |
| ~/.claude/tasks/*/ | Shared task list | Yes (auto-generated) | System-managed task coordination |
| .claude/teams/teams.json (project) | User-created | Unknown | Team role/scope reference |

Environment

• Claude Code on Windows (MSYS2/bash)
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 enabled
• Using Agent Teams since February 2026

Expected outcome

A clear section in the official docs (or a FAQ) that explicitly states:

1. Which paths are auto-recognized configuration vs reference documents
2. Whether project-level team definition files are planned for official support
3. The relationship between .claude/agents/ and Agent Teams