rhachet-roles-bhrain 0.1.1 → 0.3.0

package/dist/roles/architect/briefs/brains.replic/arc201.blueprint.claude-code.[article].md

@@ -0,0 +1,417 @@
+# blueprint: claude code
+
+## .what
+
+claude code is anthropic's official cli-based coding assistant that implements a replic brain architecture with a single-threaded agentic loop, extensive tool suite, and subagent delegation pattern.
+
+## .why
+
+understanding claude code's architecture reveals how a production replic brain balances capability, safety, and user experience. it serves as the reference implementation for the concepts documented in this brief collection.
+
+---
+
+## core agentic loop
+
+### pseudocode
+
+```python
+def run_session(user_message, context):
+    # initialize context with system prompt + conversation history
+    context_window = build_context(
+        system_prompt=SYSTEM_PROMPT,  # ~15k tokens
+        conversation_history=context.history,
+        user_message=user_message
+    )
+
+    while True:
+        # generate response from llm
+        response = llm.generate(
+            messages=context_window,
+            tools=TOOL_DEFINITIONS,
+            model="claude-sonnet-4" | "claude-opus-4"
+        )
+
+        # check for tool calls
+        if response.has_tool_calls:
+            for tool_call in response.tool_calls:
+                # permission check
+                if requires_approval(tool_call):
+                    approval = await_user_approval(tool_call)
+                    if not approval:
+                        context_window.append(rejection_message(tool_call))
+                        continue
+
+                # execute tool
+                result = execute_tool(tool_call)
+
+                # append result to context
+                context_window.append(tool_result_message(result))
+
+                # context management: summarize if approaching limit
+                if context_window.token_count > COMPACTION_THRESHOLD:
+                    context_window = summarize_and_compact(context_window)
+        else:
+            # no tool calls = task complete or awaiting user input
+            display_response(response)
+            return response
+
+        # check for mid-task user interjection (h2A queue)
+        if has_pending_user_message():
+            inject_user_message(context_window)
+```
+
+### key characteristics
+
+| aspect | implementation |
+|--------|----------------|
+| loop type | single-threaded, synchronous within session |
+| termination | llm responds without tool calls |
+| tool parallelism | multiple tools per response allowed |
+| user interjection | h2A queue for mid-task messages |
+
+### sources
+
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — agentic loop patterns
+- [Building Agents with Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk) — sdk implementation
+
+---
+
+## context management
+
+### strategy: auto-compaction via summarization
+
+```
+[context approaching 200k limit]
+         │
+         ↓
+[summarize earlier tool results + conversation]
+         │
+         ↓
+[replace verbose history with summary]
+         │
+         ↓
+[continue with fresh context headroom]
+```
+
+### context budget
+
+| component | typical size |
+|-----------|--------------|
+| system prompt | ~15k tokens |
+| tool definitions | ~5k tokens |
+| conversation history | variable |
+| tool results | variable (truncated at 30k chars) |
+| **total limit** | 200k tokens |
+
+### compaction triggers
+
+- approaching context limit
+- automatic during long sessions
+- explicit via context management tools
+
+### sources
+
+- [Claude Documentation](https://docs.anthropic.com) — 200k context window
+- [Extended Thinking](https://www.anthropic.com/news/visible-extended-thinking) — context budget allocation
+
+---
+
+## tool interface
+
+### builtin tools (~25)
+
+| category | tools |
+|----------|-------|
+| filesystem | Read, Write, Edit, Glob, Grep, NotebookEdit |
+| execution | Bash, Task, KillShell |
+| web | WebSearch, WebFetch |
+| planning | EnterPlanMode, ExitPlanMode |
+| coordination | TodoWrite, AskUserQuestion |
+| skills | Skill |
+
+### tool definition format
+
+```json
+{
+  "name": "Edit",
+  "description": "Performs exact string replacements in files",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "file_path": {
+        "type": "string",
+        "description": "Absolute path to the file to modify"
+      },
+      "old_string": {
+        "type": "string",
+        "description": "The text to replace"
+      },
+      "new_string": {
+        "type": "string",
+        "description": "The replacement text"
+      },
+      "replace_all": {
+        "type": "boolean",
+        "default": false
+      }
+    },
+    "required": ["file_path", "old_string", "new_string"]
+  }
+}
+```
+
+### permission model
+
+| permission level | behavior |
+|------------------|----------|
+| pre-approved | execute without asking |
+| requires approval | ask user before executing |
+| blocked | refuse to execute |
+
+### mcp extensibility
+
+claude code supports custom tools via Model Context Protocol:
+
+```
+┌─────────────────┐     ┌──────────────────┐
+│   Claude Code   │────▶│   MCP Server     │
+└─────────────────┘     │  (custom tools)  │
+                        └──────────────────┘
+```
+
+### sources
+
+- [Advanced Tool Use](https://www.anthropic.com/engineering/advanced-tool-use) — tool patterns
+- [MCP Specification](https://modelcontextprotocol.io/) — protocol details
+
+---
+
+## subagent pattern
+
+### subagent types
+
+| type | purpose | context |
+|------|---------|---------|
+| Explore | codebase exploration | fresh, isolated |
+| Plan | implementation planning | fresh, isolated |
+| general-purpose | complex multi-step tasks | fresh, isolated |
+| claude-code-guide | documentation lookup | fresh, isolated |
+
+### delegation mechanism
+
+```python
+# parent agent context
+parent_context = [current_conversation...]
+
+# spawn subagent
+subagent_result = Task(
+    subagent_type="Explore",
+    prompt="Find all authentication-related files",
+    model="haiku"  # can use cheaper model
+)
+
+# result returned to parent
+parent_context.append(subagent_result.summary)
+```
+
+### isolation benefits
+
+- fresh context window (no pollution from parent)
+- can use different/cheaper models
+- parallelizable for independent tasks
+- focused execution without distractions
+
+### sources
+
+- [Building Agents with Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk) — subagent patterns
+
+---
+
+## reasoning strategy
+
+claude code implements a pragmatic subset of reasoning strategies from the research literature:
+
+| strategy | implemented | mechanism |
+|----------|-------------|-----------|
+| implicit react | ✓ | trained behavior — reasoning interleaved with tool use |
+| extended thinking | ✓ | api parameter — caller configures token budget |
+| think tool | ✓ | model invokes mid-task for complex tool chains |
+| plan mode | ✓ | system prompt — proactive planning before coding |
+| evaluator-optimizer | ✓ partial | feedback loop with user/tests |
+
+### primary: implicit react
+
+claude code uses an implicit react pattern — reasoning is interleaved with tool use, but not always explicitly labeled:
+
+```
+[User: "Fix the failing test"]
+
+[Assistant reasoning (implicit):
+ "I need to understand why the test is failing.
+  Let me read the test file first."]
+
+[Tool: Read test file]
+[Tool Result: test contents]
+
+[Assistant reasoning (implicit):
+ "The test expects X but the function returns Y.
+  I need to check the implementation."]
+
+[Tool: Read implementation]
+...
+```
+
+### extended thinking integration
+
+for complex tasks, extended thinking provides additional reasoning budget:
+
+```
+[Enable extended thinking: 16k tokens]
+
+[Thinking block:
+ "This is a complex refactoring. Let me consider:
+  1. Current architecture...
+  2. Dependencies affected...
+  3. Migration strategy...
+  ..."]
+
+[Continue with plan-informed actions]
+```
+
+### strategies NOT implemented
+
+tree-of-thoughts, self-consistency, and lats are not used — too expensive for interactive coding.
+
+### deep dive
+
+see [arc201.blueprint.claude-code.zoomin.reason.[article].md](./arc201.blueprint.claude-code.zoomin.reason.[article].md) for detailed analysis of:
+- how each strategy is triggered (model behavior vs api vs system prompt)
+- why certain strategies are excluded
+- decision flow for strategy selection
+
+### sources
+
+- [The "think" Tool](https://www.anthropic.com/engineering/claude-think-tool) — explicit thinking
+- [Extended Thinking](https://www.anthropic.com/news/visible-extended-thinking) — compute scaling
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — pattern selection
+
+---
+
+## git integration
+
+### workflow
+
+```
+[Code changes]
+     │
+     ↓
+[User: "commit this"]
+     │
+     ↓
+[Run git status, git diff]
+     │
+     ↓
+[Generate commit message]
+     │
+     ↓
+[git add + git commit]
+     │
+     ↓
+[Optional: git push (if requested)]
+```
+
+### guardrails
+
+- never force push to main/master
+- never amend pushed commits
+- never skip hooks without explicit request
+- commit only when explicitly asked
+
+---
+
+## session lifecycle
+
+### initialization
+
+1. load system prompt
+2. boot configured skills/hooks
+3. summarize prior conversation (if resuming)
+4. ready for user input
+
+### execution
+
+1. receive user message
+2. run agentic loop
+3. tool calls → results → continue
+4. respond when no more tools needed
+
+### termination
+
+- user exits
+- context exhaustion (auto-compact first)
+- explicit session end
+
+---
+
+## benchmark performance
+
+| benchmark | score | notes |
+|-----------|-------|-------|
+| SWE-bench (verified) | ~49% | real github issues |
+| HumanEval | competitive | function synthesis |
+| practical coding | strong | subjective, tool-augmented |
+
+### sources
+
+- [SWE-bench Leaderboard](https://www.swebench.com/) — benchmark results
+- [AI Coding Agents Benchmark](https://render.com/blog/ai-coding-agents-benchmark) — practical comparison
+
+---
+
+## architectural summary
+
+```
+┌────────────────────────────────────────────────────────┐
+│                     CLAUDE CODE                        │
+├────────────────────────────────────────────────────────┤
+│  ┌──────────────────────────────────────────────────┐  │
+│  │              SYSTEM PROMPT (~15k)                │  │
+│  │  - persona, tools, constraints, examples         │  │
+│  └──────────────────────────────────────────────────┘  │
+│                         │                              │
+│  ┌──────────────────────▼──────────────────────────┐  │
+│  │              AGENTIC LOOP                        │  │
+│  │  while (has_tool_calls):                        │  │
+│  │    response = llm.generate()                    │  │
+│  │    for tool in response.tools:                  │  │
+│  │      result = execute(tool)                     │  │
+│  │      context.append(result)                     │  │
+│  │    if context.full: compact()                   │  │
+│  └──────────────────────────────────────────────────┘  │
+│                         │                              │
+│  ┌──────────────────────▼──────────────────────────┐  │
+│  │              TOOL LAYER                          │  │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐           │  │
+│  │  │Builtin  │ │  MCP    │ │Subagent │           │  │
+│  │  │ Tools   │ │ Servers │ │  Task   │           │  │
+│  │  └─────────┘ └─────────┘ └─────────┘           │  │
+│  └──────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## concepts utilized
+
+- [llm](./arc101.concept.llm.[article].md)
+- [context-window](./arc104.concept.context-window.[article].md)
+- [system-prompt](./arc105.concept.system-prompt.[article].md)
+- [agentic-loop](./arc109.concept.agentic-loop.[article].md)
+- [tool-definition](./arc106.concept.tool-definition.[article].md)
+- [tool-call](./arc107.concept.tool-call.[article].md)
+- [tool-result](./arc108.concept.tool-result.[article].md)
+- [context-compaction](./arc116.concept.context-compaction.[article].md)
+- [subagent](./arc117.concept.subagent.[article].md)
+- [extended-thinking](./arc118.concept.extended-thinking.[article].md)
+- [mcp](./arc119.concept.mcp.[article].md)
+- [react-pattern](./arc111.concept.react-pattern.[article].md) (implicit)