docs: Add .geminiignore configuration guidelines to improve Gemini CLI performance and context clarity

2026-02-13 02:41:50 +08:00 · 2025-09-12 15:49:38 +08:00
parent 1f6b73b4d9
commit 00ed337594
7 changed files with 148 additions and 95 deletions
--- a/.claude/commands/codex/mode/plan.md
+++ b/.claude/commands/codex/mode/plan.md
@@ -15,8 +15,9 @@ model: sonnet

 ## Overview
 Comprehensive development planning and implementation strategy using expert planning templates with Codex CLI.
+-   **Directory Analysis Rule**: When user intends to analyze specific directory (cd XXX), use: `codex --cd XXX --full-auto exec "prompt"` or `cd XXX && codex --full-auto exec "@{**/*} prompt"`
+-   **Default Mode**: `--full-auto exec` autonomous development mode (RECOMMENDED for all tasks).

-**Core Guidelines**: @~/.claude/workflows/codex-unified.md

 ⚠️ **Critical Difference**: Codex has **NO `--all-files` flag** - you MUST use `@` patterns to reference files.

@@ -26,22 +27,20 @@ Comprehensive development planning and implementation strategy using expert plan
 ```bash
 /codex:mode:plan "design authentication system with implementation"
 ```
-**Executes**: `codex exec "@{**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt)"`
+**Executes**: `codex --full-auto exec "@{**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt) design authentication system with implementation"`

 ### Architecture Planning with Context
 ```bash
 /codex:mode:plan "microservices migration strategy"
 ```
-**Executes**: `codex exec "@{src/**/*,*.config.*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/planning/migration.txt)"`
+**Executes**: `codex  --full-auto exec "@{src/**/*,*.config.*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/planning/migration.txt) microservices migration strategy"`

 ### Feature Implementation Planning
 ```bash
 /codex:mode:plan "real-time notifications with WebSocket integration"
 ```
-**Executes**: `codex exec "@{**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)

-Additional Planning Context:
-$(cat ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt)"`
+**Executes**: `codex --full-auto exec "@{**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) Additional Planning Context:$(cat ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt) real-time notifications with WebSocket integration"`

 ## Codex-Specific Planning Patterns

--- a/.claude/commands/gemini/mode/auto.md
+++ b/.claude/commands/gemini/mode/auto.md
@@ -17,6 +17,10 @@ model: sonnet
 ## Overview
 Automatically analyzes user input to select the most appropriate template and execute Gemini CLI with optimal context.

+**Directory Analysis Rule**: Intelligent detection of directory context intent - automatically navigate to target directory when analysis scope is directory-specific.
+
+**--cd Parameter Rule**: When `--cd` parameter is provided, always execute `cd [path] && gemini --all-files -p "prompt"` to ensure analysis occurs in the specified directory context.
+
 **Process**: List Templates → Analyze Input → Select Template → Execute with Context

 ## Usage
@@ -34,6 +38,9 @@ Automatically analyzes user input to select the most appropriate template and ex

 # Architecture/design keywords → selects plan.md
 /gemini:mode:auto "implement real-time chat system architecture"
+
+# With directory context
+/gemini:mode:auto "authentication issues" --cd "src/auth"
 ```

 ## Template Selection Logic
@@ -118,24 +125,19 @@ END FUNCTION

 ### Step 3: Execute with Dynamically Selected Template
 ```bash
-# Dynamic execution with selected template
+# Basic execution with selected template
 gemini --all-files -p "$(cat ~/.claude/prompt-templates/[selected_template])

-Context: @{CLAUDE.md,**/*CLAUDE.md}
+User Input: [user_input]"
+
+# With --cd parameter
+cd [specified_directory] && gemini --all-files -p "$(cat ~/.claude/prompt-templates/[selected_template])

 User Input: [user_input]"
 ```

 **Template selection is completely dynamic** - any new templates added to the directory will be automatically discovered and available for selection based on their YAML frontmatter.

-## Options
-
-| Option | Purpose |
-|--------|---------|
-| `--list-templates` | Show available templates and exit |
-| `--template <name>` | Force specific template (overrides auto-selection) |
-| `--debug` | Show template selection reasoning |
-| `--save-session` | Save results to workflow session |

 ### Manual Template Override
 ```bash
@@ -174,7 +176,7 @@ User Input: [user_input]"

 ## Session Integration

-When `--save-session` used, saves to:
+saves to:
 `.workflow/WFS-[topic]/.chat/auto-[template]-[timestamp].md`

 **Session includes:**
--- a/.claude/commands/gemini/mode/bug-index.md
+++ b/.claude/commands/gemini/mode/bug-index.md
@@ -16,18 +16,23 @@ model: sonnet
 ## Overview
 Systematic bug analysis and fix suggestions using expert diagnostic template.

+**Directory Analysis Rule**: Intelligent detection of directory context intent - automatically navigate to target directory when analysis scope is directory-specific.
+
+**--cd Parameter Rule**: When `--cd` parameter is provided, always execute `cd [path] && gemini --all-files -p "prompt"` to ensure analysis occurs in the specified directory context.
+
 ## Usage

 ### Basic Bug Analysis
 ```bash
-/gemini:mode:bug-index "authentication error during login"
+/gemini:mode:bug-index "authentication null pointer error"
 ```

-### With All Files Context
+### Bug Analysis with Directory Context
 ```bash
-/gemini:mode:bug-index "React state not updating" --all-files
+/gemini:mode:bug-index "authentication error" --cd "src/auth"
 ```

+
 ### Save to Workflow Session
 ```bash
 /gemini:mode:bug-index "API timeout issues" --save-session
@@ -39,9 +44,13 @@ Systematic bug analysis and fix suggestions using expert diagnostic template.

 **Executes**:
 ```bash
+# Basic usage
 gemini --all-files -p "$(cat ~/.claude/prompt-templates/bug-fix.md)

-Context: @{CLAUDE.md,**/*CLAUDE.md}
+Bug Description: [user_description]"
+
+# With --cd parameter
+cd [specified_directory] && gemini --all-files -p "$(cat ~/.claude/prompt-templates/bug-fix.md)

 Bug Description: [user_description]"
 ```
@@ -54,16 +63,10 @@ The bug-fix template provides:
 - **Targeted Solutions**: Specific, minimal fixes
 - **Impact Assessment**: Understanding side effects

-## Options
-
-| Option | Purpose |
-|--------|---------|
-| `--all-files` | Include entire codebase for analysis |
-| `--save-session` | Save analysis to workflow session |

 ## Session Output

-When `--save-session` used, saves to:
+saves to:
 `.workflow/WFS-[topic]/.chat/bug-index-[timestamp].md`

 **Includes:**
--- a/.claude/commands/gemini/mode/plan.md
+++ b/.claude/commands/gemini/mode/plan.md
@@ -1,6 +1,6 @@
 ---
 name: plan
-description: Project planning and architecture analysis using specialized template
+description: Project planning and architecture analysis using Gemini CLI with specialized template
 usage: /gemini:mode:plan "planning topic"
 argument-hint: "planning topic or architectural challenge to analyze"
 examples:
@@ -14,57 +14,44 @@ model: sonnet
 # Planning Analysis Command (/gemini:mode:plan)

 ## Overview
-Comprehensive project planning and architecture analysis using expert planning template.
+**This command uses Gemini CLI for comprehensive project planning and architecture analysis.** It leverages Gemini CLI's powerful codebase analysis capabilities combined with expert planning templates to provide strategic insights and implementation roadmaps.
+
+### Key Features
+- **Gemini CLI Integration**: Utilizes Gemini CLI's deep codebase analysis for informed planning decisions
+
+**--cd Parameter Rule**: When `--cd` parameter is provided, always execute `cd [path] && gemini --all-files -p "prompt"` to ensure analysis occurs in the specified directory context.

 ## Usage

-### Basic Planning Analysis
+### Basic Usage
 ```bash
 /gemini:mode:plan "design authentication system"
 ```

-### With All Files Context
+### Directory-Specific Analysis
 ```bash
-/gemini:mode:plan "microservices migration" --all-files
-```
-
-### Save to Workflow Session
-```bash
-/gemini:mode:plan "real-time notifications" --save-session
+/gemini:mode:plan "design authentication system" --cd "src/auth"
 ```

 ## Command Execution

-**Template Used**: `~/.claude/prompt-templates/plan.md`
+**Smart Directory Detection**: Auto-detects relevant directories based on topic keywords 

 **Executes**:
 ```bash
+# Project-wide analysis
 gemini --all-files -p "$(cat ~/.claude/prompt-templates/plan.md)
+Planning Topic: [user_description]"

-Context: @{CLAUDE.md,**/*CLAUDE.md}
-
+# Directory-specific analysis  
+cd [directory] && gemini --all-files -p "$(cat ~/.claude/prompt-templates/plan.md)
 Planning Topic: [user_description]"
 ```

-## Planning Focus
-
-The planning template provides:
- **Requirements Analysis**: Functional and non-functional requirements
- **Architecture Design**: System structure and interactions
- **Implementation Strategy**: Step-by-step development approach  
- **Risk Assessment**: Challenges and mitigation strategies
- **Resource Planning**: Time, effort, and technology needs
-
-## Options
-
-| Option | Purpose |
-|--------|---------|
-| `--all-files` | Include entire codebase for context |
-| `--save-session` | Save analysis to workflow session |

 ## Session Output

-When `--save-session` used, saves to:
+saves to:
 `.workflow/WFS-[topic]/.chat/plan-[timestamp].md`

 **Includes:**
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,24 +20,6 @@ This document defines project-specific coding standards and development principl
 - No clever tricks - choose the boring solution
 - If you need to explain it, it's too complex

-
-## Code Quality Standards
-
-### Code Style
-
- **Consistent formatting** - Follow project's established formatting rules
- **Meaningful names** - Variables and functions should be self-documenting
- **Small functions** - Each function should do one thing well
- **Clear structure** - Logical organization of code modules
-
-### Testing Standards
-
- **Test coverage** - Aim for high test coverage on critical paths
- **Test readability** - Tests should serve as documentation
- **Edge cases** - Consider boundary conditions and error states
- **Test isolation** - Tests should be independent and repeatable
-
-
 ## Project Integration

 ### Learning the Codebase
@@ -70,12 +52,6 @@ This document defines project-specific coding standards and development principl
 - Stop after 3 failed attempts and reassess


-### CLI Tool Context Protocols
-For all CLI tool usage, command syntax, and integration guidelines:
- **Gemini (Analysis)**: @~/.claude/workflows/gemini-unified.md
- **Codex (Analysis)**: @~/.claude/workflows/codex-unified.md
-
-
 #### **Content Uniqueness Rules**

 - **Each layer owns its abstraction level** - no content sharing between layers
@@ -83,17 +59,3 @@ For all CLI tool usage, command syntax, and integration guidelines:
 - **Maintain perspective** - each layer sees the system at its appropriate scale
 - **Avoid implementation creep** - higher layers stay architectural

-#### **Update Strategy**
-
- **Related Mode**: Update only affected modules + parent hierarchy propagation
- **Full Mode**: Complete hierarchy refresh with strict layer boundaries
- **Context Intelligence**: Automatic detection of what needs updating
-
-
-#### **Quality Assurance**
-
- **Layer Validation**: Each CLAUDE.md must stay within its layer's purpose
- **Duplication Detection**: Cross-reference content to prevent overlap
- **Hierarchy Consistency**: Parent layers reflect child changes appropriately
- **Content Relevance**: Regular cleanup of outdated or irrelevant content
-
--- a/README.md
+++ b/README.md
@@ -292,6 +292,56 @@ For optimal CCW integration, configure Gemini CLI settings:

 This setting ensures that CCW's intelligent documentation system integrates properly with Gemini CLI workflows.

+### .geminiignore Configuration
+
+To optimize Gemini CLI performance and reduce context noise, configure a `.geminiignore` file in your project root. This file excludes irrelevant files from analysis, providing cleaner context and faster processing.
+
+#### Creating .geminiignore
+Create `.geminiignore` in your project root:
+
+```bash
+# Exclude build outputs and dependencies
+/dist/
+/build/
+/node_modules/
+/.next/
+
+# Exclude temporary files
+*.tmp
+*.log
+/temp/
+
+# Exclude sensitive files
+/.env
+/config/secrets.*
+apikeys.txt
+
+# Exclude large data files
+*.csv
+*.json
+*.sql
+
+# Include important documentation (negation)
+!README.md
+!CHANGELOG.md
+!**/CLAUDE.md
+```
+
+#### Configuration Benefits
+- **Improved Performance**: Faster analysis by excluding irrelevant files
+- **Better Context**: Cleaner analysis results without build artifacts
+- **Reduced Token Usage**: Lower costs by filtering out unnecessary content
+- **Enhanced Focus**: Better AI understanding through relevant context only
+
+#### Best Practices
+- Always exclude `node_modules/`, `dist/`, `build/` directories
+- Filter out log files, temporary files, and build artifacts
+- Keep documentation files (use `!` to include specific patterns)
+- Update `.geminiignore` when project structure changes
+- Restart Gemini CLI session after modifying `.geminiignore`
+
+**Note**: Unlike `.gitignore`, `.geminiignore` only affects Gemini CLI operations and does not impact Git versioning.
+
 ## Contributing

 ### Development Setup
--- a/README_CN.md
+++ b/README_CN.md
@@ -292,6 +292,56 @@ cd src/api && /update-memory-related

 此设置确保CCW的智能文档系统能够与Gemini CLI工作流正确集成。

+### .geminiignore 配置
+
+为了优化Gemini CLI性能并减少上下文噪声，请在项目根目录配置 `.geminiignore` 文件。此文件可以排除无关文件的分析，提供更清洁的上下文和更快的处理速度。
+
+#### 创建 .geminiignore
+在项目根目录创建 `.geminiignore` 文件：
+
+```bash
+# 排除构建输出和依赖项
+/dist/
+/build/
+/node_modules/
+/.next/
+
+# 排除临时文件
+*.tmp
+*.log
+/temp/
+
+# 排除敏感文件
+/.env
+/config/secrets.*
+apikeys.txt
+
+# 排除大型数据文件
+*.csv
+*.json
+*.sql
+
+# 包含重要文档（取反模式）
+!README.md
+!CHANGELOG.md
+!**/CLAUDE.md
+```
+
+#### 配置优势
+- **提升性能**: 通过排除无关文件实现更快的分析速度
+- **更好的上下文**: 没有构建产物的更清洁分析结果
+- **减少令牌使用**: 通过过滤不必要内容降低成本
+- **增强专注度**: 通过相关上下文获得更好的AI理解
+
+#### 最佳实践
+- 始终排除 `node_modules/`、`dist/`、`build/` 目录
+- 过滤日志文件、临时文件和构建产物
+- 保留文档文件（使用 `!` 包含特定模式）
+- 项目结构变更时更新 `.geminiignore`
+- 修改 `.geminiignore` 后重启Gemini CLI会话
+
+**注意**: 与 `.gitignore` 不同，`.geminiignore` 仅影响Gemini CLI操作，不会影响Git版本控制。
+
 ## 贡献

 ### 开发设置