From 48c6fa9a40243e3bbe51b476d565be52882ce8c5 Mon Sep 17 00:00:00 2001
From: catlog22 <catlog22@github.com>
Date: Sat, 4 Oct 2025 09:55:00 +0800
Subject: [PATCH] docs: Update documentation for git staging and MCP
 recommendations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add pre-execution git staging to codex-execute workflow for clear change visibility
- Update README to recommend MCP tools installation (not optional)
- Add core principle: no unsolicited reports without user permission

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .claude/commands/cli/codex-execute.md | 19 ++++++++++++++++---
 CLAUDE.md                             |  2 ++
 README.md                             | 12 +++++++++---
 3 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/.claude/commands/cli/codex-execute.md b/.claude/commands/cli/codex-execute.md
index 0c6196e5..11e585c0 100644
--- a/.claude/commands/cli/codex-execute.md
+++ b/.claude/commands/cli/codex-execute.md
@@ -24,6 +24,7 @@ Automated task decomposition and sequential execution with Codex, using `codex e
 ```
 Task Input → Decompose into Subtasks → TodoWrite Tracking →
 For Each Subtask:
+  0. Stage existing changes (git add -A) if valid git repo
   1. Execute with Codex
   2. [Optional] Git verification
   3. Mark complete in TodoWrite
@@ -61,6 +62,14 @@ For Each Subtask:
 
 ### Phase 2: Sequential Execution
 
+**Pre-Execution Git Staging** (if valid git repository):
+```bash
+# Stage all current changes before codex execution
+# This makes codex changes clearly visible in git diff
+git add -A
+git status --short
+```
+
 **For First Subtask**:
 ```bash
 # Initial execution (no resume needed)
@@ -76,6 +85,9 @@ Subtask 1 of N: [subtask title]
 
 **For Subsequent Subtasks** (using resume --last):
 ```bash
+# Stage changes from previous subtask (if valid git repository)
+git add -A
+
 # Resume previous session for context continuity
 codex exec "
 CONTINUE TO NEXT SUBTASK:
@@ -271,9 +283,10 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 1. **Subtask Granularity**: Keep subtasks small and focused
 2. **Clear Boundaries**: Each subtask should have well-defined input/output
 3. **Git Hygiene**: Use `--verify-git` for critical refactoring
-4. **Context Continuity**: Let `codex resume --last` maintain context
-5. **Recovery Points**: TodoWrite provides clear progress tracking
-6. **Image References**: Attach design files for UI tasks
+4. **Pre-Execution Staging**: Stage changes before each subtask to clearly see codex modifications
+5. **Context Continuity**: Let `codex resume --last` maintain context
+6. **Recovery Points**: TodoWrite provides clear progress tracking
+7. **Image References**: Attach design files for UI tasks
 
 ## Input Processing
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 0fbb3b39..17b0f024 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,6 +28,7 @@ For all CLI tool usage, command syntax, and integration guidelines:
 - **Learning from existing code** - Study and plan before implementing
 - **Clear intent over clever code** - Be boring and obvious
 - **Follow existing code style** - Match import patterns, naming conventions, and formatting of existing codebase
+- **No unsolicited reports** - Task summaries can be performed internally, but NEVER generate additional reports, documentation files, or summary files without explicit user permission
 
 ### Simplicity Means
 
@@ -56,6 +57,7 @@ For all CLI tool usage, command syntax, and integration guidelines:
 
 **NEVER**:
 - Make assumptions - verify with existing code
+- Generate reports, summaries, or documentation files without explicit user request
 
 **ALWAYS**:
 - Plan complex tasks thoroughly before implementation
diff --git a/README.md b/README.md
index 80666893..0bfdc088 100644
--- a/README.md
+++ b/README.md
@@ -335,9 +335,9 @@ Optimize performance by excluding unnecessary files:
 !**/CLAUDE.md
 ```
 
-### **Optional: MCP Tools** *(Enhanced Analysis)*
+### **Recommended: MCP Tools** *(Enhanced Analysis)*
 
-MCP (Model Context Protocol) tools provide advanced codebase analysis. **Completely optional** - CCW works perfectly without them.
+MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recommended installation** - While CCW has fallback mechanisms, not installing MCP tools may lead to unexpected behavior or degraded performance in some workflows.
 
 #### Available MCP Servers
 
@@ -350,7 +350,13 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Complet
 - 📊 **Faster Analysis**: Direct codebase indexing vs manual searching
 - 🌐 **External Context**: Real-world API patterns and examples
 - 🔍 **Advanced Search**: Pattern matching and similarity detection
-- ⚡ **Automatic Fallback**: Uses traditional tools when MCP unavailable
+- ⚡ **Better Reliability**: Primary tools for certain workflows
+
+⚠️ **Note**: Some workflows expect MCP tools to be available. Without them, you may experience:
+- Slower code analysis and search operations
+- Reduced context quality in some scenarios
+- Fallback to less efficient traditional tools
+- Potential unexpected behavior in advanced workflows
 
 ---