From a06ed852bf6d6a6c74f2a9e443476b3347c2fb3c Mon Sep 17 00:00:00 2001 From: catlog22 Date: Wed, 10 Sep 2025 22:43:04 +0800 Subject: [PATCH] refactor: Extract shared template system into independent documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create shared-template-system.md as unified template reference for both Gemini and Codex - Extract duplicate template directory structures from gemini-unified.md and codex-unified.md - Add comprehensive template categorization with tool compatibility matrix - Include cross-tool usage patterns and selection guidelines - Update both workflow files to reference shared template documentation - Maintain tool-specific template selection guides with clear focus areas - Add proper cross-references and usage examples for maintainability This eliminates duplication while providing comprehensive template system documentation that can be maintained independently. ๐Ÿค– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/workflows/codex-unified.md | 59 +++--- .claude/workflows/gemini-unified.md | 49 ++--- .claude/workflows/shared-template-system.md | 187 ++++++++++++++++++++ 3 files changed, 228 insertions(+), 67 deletions(-) create mode 100644 .claude/workflows/shared-template-system.md diff --git a/.claude/workflows/codex-unified.md b/.claude/workflows/codex-unified.md index ca9be3f2..0d59161e 100644 --- a/.claude/workflows/codex-unified.md +++ b/.claude/workflows/codex-unified.md @@ -71,45 +71,32 @@ type: technical-guideline ### ๐Ÿ“ Shared Template Directory Structure -Templates are shared between gemini and codex. This structure must be located at `~/.claude/workflows/cli-templates/`. +> **๐Ÿ“‹ Complete Template Reference**: See [Shared Template System](./shared-template-system.md) for comprehensive template directory structure, cross-tool compatibility, and detailed usage patterns. -``` -~/.claude/workflows/cli-templates/ -โ”œโ”€โ”€ prompts/ -โ”‚ โ”œโ”€โ”€ development/ # Automated development templates -โ”‚ โ”‚ โ”œโ”€โ”€ feature.txt # ๐Ÿ”ง Feature implementation & integration -โ”‚ โ”‚ โ”œโ”€โ”€ component.txt # ๐Ÿงฉ Component design & development -โ”‚ โ”‚ โ”œโ”€โ”€ refactor.txt # ๐Ÿ”„ Code refactoring & optimization -โ”‚ โ”‚ โ”œโ”€โ”€ testing.txt # ๐Ÿงช Test generation & validation -โ”‚ โ”‚ โ””โ”€โ”€ debugging.txt # ๐Ÿ› Bug analysis & resolution -โ”‚ โ”œโ”€โ”€ automation/ # Autonomous workflow templates -โ”‚ โ”‚ โ”œโ”€โ”€ scaffold.txt # ๐Ÿ—๏ธ Project scaffolding & setup -โ”‚ โ”‚ โ”œโ”€โ”€ migration.txt # ๐Ÿš€ Automated migration & upgrades -โ”‚ โ”‚ โ””โ”€โ”€ deployment.txt # ๐Ÿšข CI/CD & deployment automation -โ”‚ โ”œโ”€โ”€ analysis/ # Inherited from gemini templates -โ”‚ โ”‚ โ”œโ”€โ”€ pattern.txt # โœจ Implementation patterns & conventions -โ”‚ โ”‚ โ”œโ”€โ”€ architecture.txt # ๐Ÿ—๏ธ System architecture & dependencies -โ”‚ โ”‚ โ”œโ”€โ”€ security.txt # ๐Ÿ”’ Security vulnerabilities & protection -โ”‚ โ”‚ โ”œโ”€โ”€ performance.txt # โšก Performance bottlenecks & optimization -โ”‚ โ”‚ โ””โ”€โ”€ quality.txt # ๐Ÿ“Š Code quality & maintainability -โ”‚ โ””โ”€โ”€ integration/ # Cross-system templates -โ”‚ โ”œโ”€โ”€ api-design.txt # ๐ŸŒ API design & implementation -โ”‚ โ””โ”€โ”€ database.txt # ๐Ÿ—„๏ธ Database schema & operations -โ””โ”€โ”€ commands/ # Command examples and patterns -``` +#### Template System Overview +Codex uses a shared template system with Gemini, located at `~/.claude/workflows/cli-templates/`. Templates are organized by primary use case: -### ๐Ÿงญ Template Selection Guide +- **`development/`** - Development templates (Codex primary) +- **`automation/`** - Autonomous workflow templates (Codex specialized) +- **`analysis/`** - Analysis templates (Gemini primary, Codex compatible) +- **`integration/`** - Cross-system templates (Codex primary) +- **`planning/`** - Planning templates (Cross-tool) +- **`review/`** - Review templates (Cross-tool) + +### ๐Ÿงญ Template Selection Guide (Codex Focus) | Task Type | Primary Template | Purpose | Codex Advantage | |---|---|---|---| -| Build New Feature | `feature.txt` | End-to-end feature development | Autonomous implementation | -| Create Component | `component.txt` | Reusable component development | Pattern-aware generation | -| Refactor Code | `refactor.txt` | Code improvement & optimization | Context-aware refactoring | -| Generate Tests | `testing.txt` | Comprehensive test coverage | Intelligent test generation | -| Debug Issues | `debugging.txt` | Problem analysis & resolution | Root cause identification | -| Scaffold Project | `scaffold.txt` | Project structure creation | Best practice templates | -| Migrate Systems | `migration.txt` | Technology upgrades | Automated migration paths | -| API Development | `api-design.txt` | API design & implementation | RESTful pattern adherence | +| Build New Feature | `development/feature.txt` | End-to-end feature development | Autonomous implementation | +| Create Component | `development/component.txt` | Reusable component development | Pattern-aware generation | +| Refactor Code | `development/refactor.txt` | Code improvement & optimization | Context-aware refactoring | +| Generate Tests | `development/testing.txt` | Comprehensive test coverage | Intelligent test generation | +| Debug Issues | `development/debugging.txt` | Problem analysis & resolution | Root cause identification | +| Scaffold Project | `automation/scaffold.txt` | Project structure creation | Best practice templates | +| Automate Migration | `automation/migration.txt` | Technology upgrades | Automated migration paths | +| API Development | `integration/api-design.txt` | API design & implementation | RESTful pattern adherence | + +> **๐Ÿ’ก Cross-Tool Usage**: Analysis templates (`analysis/`) work with Codex for understanding existing code before development. See shared template system for complete compatibility matrix. ### ๐Ÿ“ฆ Standard Command Structures @@ -121,8 +108,8 @@ Templates are shared between gemini and codex. This structure must be located at # Alternative: use --cd flag to navigate + include folder codex --cd src/auth exec "@{**/*,../../CLAUDE.md} Implement JWT refresh token functionality" - # For comprehensive module analysis - codex exec "@{backend/services/**/*,package.json,CLAUDE.md} Optimize service layer performance" + # Template-enhanced development (see shared-template-system.md for all available templates) + codex exec "@{backend/services/**/*,package.json,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/refactor.txt)" ``` - **Basic Development Task** diff --git a/.claude/workflows/gemini-unified.md b/.claude/workflows/gemini-unified.md index 11f498c5..fcc4a808 100644 --- a/.claude/workflows/gemini-unified.md +++ b/.claude/workflows/gemini-unified.md @@ -68,40 +68,27 @@ type: technical-guideline ### TPL (Templates) -#### ๐Ÿ—‚๏ธ Shared Template Directory Structure -Templates are shared between gemini and codex. This structure can be located at either `~/.claude/workflows/cli-templates/` (global) or `./.claude/workflows/cli-templates/` (project-specific). +> **๐Ÿ“‹ Complete Template Reference**: See [Shared Template System](./shared-template-system.md) for comprehensive template directory structure, selection guide, and cross-tool compatibility details. -~/.claude/workflows/cli-templates/ -โ”œโ”€โ”€ prompts/ -โ”‚ โ”œโ”€โ”€ analysis/ # Code analysis templates -โ”‚ โ”‚ โ”œโ”€โ”€ pattern.txt # โœจ Implementation patterns & conventions -โ”‚ โ”‚ โ”œโ”€โ”€ architecture.txt # ๐Ÿ—๏ธ System architecture & dependencies -โ”‚ โ”‚ โ”œโ”€โ”€ security.txt # ๐Ÿ”’ Security vulnerabilities & protection -โ”‚ โ”‚ โ”œโ”€โ”€ performance.txt # โšก Performance bottlenecks & optimization -โ”‚ โ”‚ โ””โ”€โ”€ quality.txt # ๐Ÿ“Š Code quality & maintainability -โ”‚ โ”œโ”€โ”€ planning/ # Planning templates -โ”‚ โ”‚ โ”œโ”€โ”€ task-breakdown.txt # ๐Ÿ“‹ Task decomposition & dependencies -โ”‚ โ”‚ โ””โ”€โ”€ migration.txt # ๐Ÿš€ System migration & modernization -โ”‚ โ”œโ”€โ”€ implementation/ # Development templates -โ”‚ โ”‚ โ””โ”€โ”€ component.txt # ๐Ÿงฉ Component design & implementation -โ”‚ โ”œโ”€โ”€ review/ # Review templates -โ”‚ โ”‚ โ””โ”€โ”€ code-review.txt # โœ… Comprehensive review checklist -โ”‚ โ””โ”€โ”€ dms/ # DMS-specific -โ”‚ โ””โ”€โ”€ hierarchy-analysis.txt # ๐Ÿ“š Documentation structure optimization -โ””โ”€โ”€ commands/ # Command examples +#### ๐Ÿ—‚๏ธ Template System Overview +Gemini uses a shared template system with Codex, located at `~/.claude/workflows/cli-templates/`. Templates are organized by primary use case: +- **`analysis/`** - Code analysis templates (Gemini primary) +- **`development/`** - Development templates (Codex primary, Gemini compatible) +- **`planning/`** - Planning templates (Cross-tool) +- **`review/`** - Review templates (Cross-tool) -#### ๐Ÿงญ Template Selection Guide -| Task Type | Primary Template | Purpose | +#### ๐Ÿงญ Quick Template Selection (Gemini Focus) +| Task Type | Primary Template | Usage Pattern | |---|---|---| -| Understand Existing Code | `pattern.txt` | Codebase learning, onboarding. | -| Plan New Features | `task-breakdown.txt`| Feature development planning. | -| Security Review | `security.txt` | Security audits, vulnerability assessment. | -| Performance Tuning | `performance.txt` | Bottleneck investigation. | -| Code Quality Improvement | `quality.txt` | Refactoring, technical debt reduction. | -| System Modernization | `migration.txt` | Tech upgrades, architectural changes. | -| Component Development | `component.txt` | Building reusable components. | -| Pre-Release Review | `code-review.txt` | Release readiness checks. | +| Understand Existing Code | `analysis/pattern.txt` | Analysis & onboarding | +| Security Review | `analysis/security.txt` | Vulnerability assessment | +| Performance Analysis | `analysis/performance.txt` | Bottleneck investigation | +| Code Quality Assessment | `analysis/quality.txt` | Technical debt review | +| Architecture Review | `analysis/architecture.txt` | System design analysis | +| Plan New Features | `planning/task-breakdown.txt` | Development planning | + +> **๐Ÿ’ก Template Usage**: All templates work with both `$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)` syntax and multi-template composition patterns. ### ๐Ÿ“ฆ Standard Command Structures @@ -116,7 +103,7 @@ These are recommended command templates for common scenarios. # Or specify module from root directory cd backend/services && gemini --all-files -p "Review service architecture and dependencies" - # Template-enhanced module analysis + # Template-enhanced module analysis (see shared-template-system.md for all available templates) cd frontend/components && gemini --all-files -p "$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)" ``` diff --git a/.claude/workflows/shared-template-system.md b/.claude/workflows/shared-template-system.md new file mode 100644 index 00000000..3f670265 --- /dev/null +++ b/.claude/workflows/shared-template-system.md @@ -0,0 +1,187 @@ +--- +name: shared-template-system +description: Unified template directory structure and organization for Gemini and Codex CLI integration +type: system-architecture +--- + +# ๐Ÿ—‚๏ธ Shared Template System + +## Overview + +This document defines the unified template system shared between Gemini (analysis) and Codex (development) CLI tools. The template system provides standardized, reusable prompts for common software development and analysis tasks. + +## ๐Ÿ“ Template Directory Structure + +Templates are shared between gemini and codex. This structure can be located at either `~/.claude/workflows/cli-templates/` (global) or `./.claude/workflows/cli-templates/` (project-specific). + +``` +~/.claude/workflows/cli-templates/ +โ”œโ”€โ”€ prompts/ +โ”‚ โ”œโ”€โ”€ analysis/ # Code analysis templates (Gemini primary, Codex compatible) +โ”‚ โ”‚ โ”œโ”€โ”€ pattern.txt # โœจ Implementation patterns & conventions +โ”‚ โ”‚ โ”œโ”€โ”€ architecture.txt # ๐Ÿ—๏ธ System architecture & dependencies +โ”‚ โ”‚ โ”œโ”€โ”€ security.txt # ๐Ÿ”’ Security vulnerabilities & protection +โ”‚ โ”‚ โ”œโ”€โ”€ performance.txt # โšก Performance bottlenecks & optimization +โ”‚ โ”‚ โ””โ”€โ”€ quality.txt # ๐Ÿ“Š Code quality & maintainability +โ”‚ โ”œโ”€โ”€ development/ # Automated development templates (Codex primary) +โ”‚ โ”‚ โ”œโ”€โ”€ feature.txt # ๐Ÿ”ง Feature implementation & integration +โ”‚ โ”‚ โ”œโ”€โ”€ component.txt # ๐Ÿงฉ Component design & development +โ”‚ โ”‚ โ”œโ”€โ”€ refactor.txt # ๐Ÿ”„ Code refactoring & optimization +โ”‚ โ”‚ โ”œโ”€โ”€ testing.txt # ๐Ÿงช Test generation & validation +โ”‚ โ”‚ โ””โ”€โ”€ debugging.txt # ๐Ÿ› Bug analysis & resolution +โ”‚ โ”œโ”€โ”€ planning/ # Planning templates (Cross-tool) +โ”‚ โ”‚ โ”œโ”€โ”€ task-breakdown.txt # ๐Ÿ“‹ Task decomposition & dependencies +โ”‚ โ”‚ โ””โ”€โ”€ migration.txt # ๐Ÿš€ System migration & modernization +โ”‚ โ”œโ”€โ”€ automation/ # Autonomous workflow templates (Codex primary) +โ”‚ โ”‚ โ”œโ”€โ”€ scaffold.txt # ๐Ÿ—๏ธ Project scaffolding & setup +โ”‚ โ”‚ โ”œโ”€โ”€ migration.txt # ๐Ÿš€ Automated migration & upgrades +โ”‚ โ”‚ โ””โ”€โ”€ deployment.txt # ๐Ÿšข CI/CD & deployment automation +โ”‚ โ”œโ”€โ”€ review/ # Review templates (Cross-tool) +โ”‚ โ”‚ โ””โ”€โ”€ code-review.txt # โœ… Comprehensive review checklist +โ”‚ โ”œโ”€โ”€ integration/ # Cross-system templates (Codex primary) +โ”‚ โ”‚ โ”œโ”€โ”€ api-design.txt # ๐ŸŒ API design & implementation +โ”‚ โ”‚ โ””โ”€โ”€ database.txt # ๐Ÿ—„๏ธ Database schema & operations +โ”‚ โ””โ”€โ”€ dms/ # DMS-specific templates (Project-specific) +โ”‚ โ””โ”€โ”€ hierarchy-analysis.txt # ๐Ÿ“š Documentation structure optimization +โ””โ”€โ”€ commands/ # Command examples and patterns +``` + +## ๐Ÿ“Š Template Categories + +### Analysis Templates (`analysis/`) +**Primary Tool**: Gemini | **Compatibility**: Codex +- Focus on understanding, investigating, and analyzing existing code +- Used for codebase learning, pattern recognition, and architectural analysis +- Compatible with both tools but optimized for Gemini's analysis capabilities + +### Development Templates (`development/`) +**Primary Tool**: Codex | **Compatibility**: Gemini +- Focus on creating, modifying, and implementing code +- Used for feature development, refactoring, and code generation +- Optimized for Codex's autonomous development capabilities + +### Planning Templates (`planning/`) +**Primary Tool**: Both | **Cross-tool Compatibility** +- Focus on strategic planning and architectural decisions +- Used for task decomposition, migration planning, and system design +- Equally effective with both Gemini and Codex + +### Automation Templates (`automation/`) +**Primary Tool**: Codex | **Limited Gemini Use** +- Focus on automated workflows and system setup +- Used for scaffolding, deployment, and infrastructure automation +- Specifically designed for Codex's autonomous capabilities + +### Review Templates (`review/`) +**Primary Tool**: Both | **Cross-tool Compatibility** +- Focus on quality assurance and validation +- Used for code review, testing validation, and release readiness +- Effective for both analysis (Gemini) and implementation validation (Codex) + +### Integration Templates (`integration/`) +**Primary Tool**: Codex | **Gemini Analysis Support** +- Focus on system integration and cross-service development +- Used for API development, database operations, and service integration +- Codex implements, Gemini can analyze existing integrations + +## ๐Ÿงญ Template Selection Guide + +### For Analysis Tasks (Gemini Primary) +| Task Type | Template | Purpose | Tool Recommendation | +|-----------|----------|---------|-------------------| +| Understand Existing Code | `analysis/pattern.txt` | Codebase learning, onboarding | Gemini | +| Security Review | `analysis/security.txt` | Security audits, vulnerability assessment | Gemini | +| Performance Analysis | `analysis/performance.txt` | Bottleneck investigation | Gemini | +| Code Quality Assessment | `analysis/quality.txt` | Technical debt, maintainability review | Gemini | +| Architecture Review | `analysis/architecture.txt` | System design analysis | Gemini | + +### For Development Tasks (Codex Primary) +| Task Type | Template | Purpose | Tool Recommendation | +|-----------|----------|---------|-------------------| +| Build New Feature | `development/feature.txt` | End-to-end feature development | Codex | +| Create Component | `development/component.txt` | Reusable component development | Codex | +| Refactor Code | `development/refactor.txt` | Code improvement & optimization | Codex | +| Generate Tests | `development/testing.txt` | Comprehensive test coverage | Codex | +| Debug Issues | `development/debugging.txt` | Problem analysis & resolution | Codex | + +### For Planning Tasks (Cross-tool) +| Task Type | Template | Purpose | Tool Recommendation | +|-----------|----------|---------|-------------------| +| Plan New Features | `planning/task-breakdown.txt` | Feature development planning | Both | +| System Modernization | `planning/migration.txt` | Tech upgrades, architectural changes | Both | +| Pre-Release Review | `review/code-review.txt` | Release readiness checks | Both | + +### For Automation Tasks (Codex Specialized) +| Task Type | Template | Purpose | Tool Recommendation | +|-----------|----------|---------|-------------------| +| Scaffold Project | `automation/scaffold.txt` | Project structure creation | Codex | +| Automate Migration | `automation/migration.txt` | Automated system upgrades | Codex | +| Setup Deployment | `automation/deployment.txt` | CI/CD pipeline automation | Codex | + +## ๐Ÿ”„ Template Usage Patterns + +### Gemini Template Usage +```bash +# Analysis template usage +gemini --all-files -p "@{src/**/*} @{CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)" + +# Multi-template composition +gemini -p "@{src/**/*} @{CLAUDE.md} +$(cat ~/.claude/workflows/cli-templates/prompts/analysis/security.txt) + +Additional Performance Focus: +$(cat ~/.claude/workflows/cli-templates/prompts/analysis/performance.txt)" +``` + +### Codex Template Usage +```bash +# Development template usage +codex exec "@{src/**/*,CLAUDE.md} $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt)" + +# Multi-template composition +codex exec "@{**/*,CLAUDE.md} +$(cat ~/.claude/workflows/cli-templates/prompts/development/component.txt) + +Security Integration: +$(cat ~/.claude/workflows/cli-templates/prompts/analysis/security.txt)" +``` + +## ๐Ÿ“ Template Maintenance Guidelines + +### Template Creation +1. **Single Responsibility**: Each template should focus on one specific task type +2. **Tool Compatibility**: Consider both Gemini and Codex usage patterns +3. **Clear Instructions**: Include specific output requirements and format expectations +4. **Reusability**: Write templates that work across different project types + +### Template Organization +1. **Consistent Naming**: Use descriptive, consistent file naming conventions +2. **Category Separation**: Keep templates in appropriate category directories +3. **Documentation**: Include inline comments explaining template purpose and usage +4. **Version Control**: Track template changes and maintain backwards compatibility + +### Cross-Tool Compatibility +1. **Analysis Templates**: Should work with both Gemini's `--all-files` and Codex's `@{}` patterns +2. **Development Templates**: Should provide clear implementation guidance for Codex while remaining analyzable by Gemini +3. **Shared Context**: Ensure templates reference `CLAUDE.md` and common project structures + +## ๐ŸŽฏ Best Practices + +### Template Selection +- **Start with Primary Tool**: Use the tool most suited for the template's primary purpose +- **Complement with Secondary**: Use the other tool for validation and cross-verification +- **Combine When Needed**: Use multi-template composition for complex tasks + +### Template Customization +- **Project-Specific Templates**: Create in `./.claude/workflows/cli-templates/` for project-specific needs +- **Global Templates**: Maintain in `~/.claude/workflows/cli-templates/` for reusable patterns +- **Template Inheritance**: Build on existing templates rather than creating from scratch + +### Quality Assurance +- **Test Both Tools**: Verify templates work effectively with both Gemini and Codex +- **Validate Output**: Ensure templates produce consistent, high-quality results +- **Regular Updates**: Keep templates current with evolving development practices + +--- + +This shared template system enables consistent, high-quality interactions with both Gemini (analysis) and Codex (development) CLI tools while maintaining clear separation of concerns and optimal tool utilization. \ No newline at end of file