Agent skill
codex-design
Consult Codex for architectural decisions. Use when: (1) introducing patterns not in codebase, (2) 3+ design options exist, (3) performance-critical implementation, (4) major refactoring. Get risk assessment before coding.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/codex-design-takumi12311123-dotfiles
SKILL.md
Codex Design Consultation
🎯 Purpose
設計段階でのCodex相談: Consult with Codex before making complex design decisions. Get expert validation, alternative approaches, and risk assessment early in the development process.
📋 When to Use
Mandatory Triggers
- Introducing implementation patterns NOT found in existing codebase
- Architecture decision with 3+ viable options
- Performance-critical implementations (high-traffic endpoints, real-time processing, etc.)
- Major refactoring affecting multiple modules
- New technology/framework introduction
- Security-sensitive design (authentication, authorization, cryptography)
Optional but Recommended
- Database schema design for new features
- API design for public/external consumption
- Distributed system component design
- Complex algorithm implementation
🔄 Consultation Flow
Step 1: Problem Analysis
Claude Code analyzes the design problem:
- Current situation and constraints
- Requirements (functional and non-functional)
- Existing codebase patterns
- Performance/security requirements
- Team expertise and maintenance considerations
Step 2: Generate Design Options
Claude Code proposes 2-3 viable approaches:
markdown
## Option 1: [Approach Name]
**Pros:**
- [Advantage 1]
- [Advantage 2]
**Cons:**
- [Drawback 1]
- [Drawback 2]
**Implementation Complexity:** Low/Medium/High
**Maintenance Cost:** Low/Medium/High
**Performance Impact:** Low/Medium/High
## Option 2: [Approach Name]
...
## Option 3: [Approach Name]
...
Step 3: Codex Consultation
Execute Codex in read-only sandbox for design review:
bash
codex exec --sandbox read-only "$(cat <<'EOF'
# Design Consultation Request
## Context
[プロジェクトの概要と現在の状況]
## Problem Statement
[解決したい問題の詳細な説明]
## Constraints
- Performance: [パフォーマンス要件]
- Security: [セキュリティ要件]
- Scalability: [スケーラビリティ要件]
- Maintainability: [保守性要件]
- Team: [チームのスキルセット]
- Timeline: [スケジュール制約]
## Proposed Design Options
### Option 1: [アプローチ名]
[詳細な説明]
**Pros:**
- [メリット1]
- [メリット2]
**Cons:**
- [デメリット1]
- [デメリット2]
### Option 2: [アプローチ名]
[詳細な説明]
...
### Option 3: [アプローチ名]
[詳細な説明]
...
## Existing Codebase Patterns
[既存のコードベースで使用されているパターン]
## Questions for Codex
1. 各アプローチの妥当性評価
2. 見落としている潜在的な問題点
3. 推奨されるアプローチとその理由
4. 実装時の注意点
5. 類似プロジェクトでの成功/失敗事例
## Required Output Format (JSON in Japanese)
以下のJSON形式で回答してください:
{
"recommended_option": "Option 1|Option 2|Option 3|Alternative",
"reasoning": "推奨理由の詳細説明(日本語)",
"risk_assessment": {
"option_1": {
"technical_risks": ["リスク1", "リスク2"],
"mitigation": ["対策1", "対策2"]
},
"option_2": { ... },
"option_3": { ... }
},
"additional_considerations": [
{
"category": "performance|security|maintainability|scalability",
"point": "考慮すべき点(日本語)",
"importance": "critical|high|medium|low"
}
],
"alternative_approach": {
"description": "代替アプローチの説明(Option 1-3以外に良い方法があれば)",
"why_better": "なぜこちらが良いか"
},
"implementation_guidance": [
"実装時のガイダンス1",
"実装時のガイダンス2"
],
"similar_patterns": [
{
"project": "類似プロジェクト名",
"approach": "採用されたアプローチ",
"outcome": "結果(成功/失敗とその理由)"
}
],
"confidence": "high|medium|low",
"caveats": ["注意事項1", "注意事項2"]
}
EOF
)"
Step 4: Analysis and Synthesis
Claude Code analyzes Codex's response:
- Evaluate recommendation validity
- Consider project-specific context
- Synthesize with existing codebase patterns
- Identify any conflicting advice
Step 5: Present to User
Present comprehensive analysis to user for final decision:
markdown
## 設計相談結果: [問題のタイトル]
### 問題概要
[解決したい問題の簡潔な説明]
### 提案した設計オプション
1. **Option 1**: [概要]
2. **Option 2**: [概要]
3. **Option 3**: [概要]
### Codex推奨
- **推奨アプローチ**: Option 2
- **信頼度**: High
- **推奨理由**:
[Codexの推奨理由を日本語で説明]
### リスク評価
#### Option 1: [名前]
- **技術的リスク**:
- [リスク1]
- [リスク2]
- **リスク軽減策**:
- [対策1]
- [対策2]
#### Option 2: [名前] ⭐ 推奨
- **技術的リスク**:
- [リスク1]
- **リスク軽減策**:
- [対策1]
#### Option 3: [名前]
- **技術的リスク**:
- [リスク1]
- [リスク2]
- **リスク軽減策**:
- [対策1]
### 追加考慮事項
#### Critical
- [重要な考慮点1]
#### High
- [高優先度の考慮点1]
- [高優先度の考慮点2]
#### Medium
- [中優先度の考慮点1]
### 代替アプローチ (Codex提案)
[Codexが提案した代替案があれば]
**なぜ良いか**: [理由]
### 実装ガイダンス
1. [実装時の注意点1]
2. [実装時の注意点2]
3. [実装時の注意点3]
### 類似プロジェクトの事例
- **プロジェクト**: [名前]
- **アプローチ**: [採用手法]
- **結果**: [成功/失敗の理由]
### 注意事項
- [注意事項1]
- [注意事項2]
### Claude Codeの所見
[Codexの推奨を踏まえた、プロジェクト固有の考察]
どのアプローチで進めますか? または、さらに詳細を検討しますか?
🔍 Specific Use Cases
Use Case 1: Database Schema Design
markdown
## Problem
新しいマルチテナント機能のためのデータベース設計
## Options
1. Single database with tenant_id column
2. Database per tenant
3. Schema per tenant (PostgreSQL)
[Codex consultation...]
## Codex Recommendation
Option 3 (Schema per tenant) for this scale
- Reasoning: Balance of isolation and management
- Risk: Schema migration complexity
- Mitigation: Use migration tool like Flyway
Use Case 2: API Design Pattern
markdown
## Problem
新しいマイクロサービス間のAPI設計
## Options
1. REST with JSON
2. gRPC
3. GraphQL
[Codex consultation...]
## Codex Recommendation
Option 2 (gRPC) for internal services
- Reasoning: Type safety, performance, streaming support
- Risk: Steeper learning curve
- Mitigation: Start with simple unary calls, add streaming later
Use Case 3: State Management
markdown
## Problem
React アプリケーションの状態管理
## Options
1. Redux Toolkit
2. Zustand
3. Jotai
[Codex consultation...]
## Codex Recommendation
Option 2 (Zustand) for this project size
- Reasoning: Simplicity, less boilerplate, sufficient for current needs
- Risk: Might need migration if app grows significantly
- Mitigation: Keep state logic modular for easier migration
🚨 Error Handling
Codex Timeout
- Wait up to 10 minutes (10 polls)
- If timeout: Present options to user without Codex input
- Explain that consultation couldn't complete
Codex API Failure
- Retry once after 5 seconds
- If retry fails: Proceed with Claude Code's analysis only
- Inform user that external validation unavailable
Conflicting Recommendations
- If Codex recommendation contradicts project constraints
- Claude Code highlights the conflict
- Provides reasoning for both perspectives
- Lets user make informed decision
📊 Output Quality Indicators
High Confidence Output
- Clear recommendation with strong reasoning
- Multiple supporting examples
- Specific implementation guidance
- Risk assessment with mitigations
Low Confidence Output
- Multiple viable options with trade-offs
- Insufficient context for firm recommendation
- Suggests gathering more information
- Recommends prototyping or spike
🔧 Configuration Parameters
| Parameter | Default | Description |
|---|---|---|
| timeout_minutes | 10 | Codex consultation timeout |
| min_options | 2 | Minimum design options to present |
| max_options | 4 | Maximum design options to present |
| require_risk_assessment | true | Require risk analysis for each option |
| include_examples | true | Include similar project examples |
🎯 Success Criteria
Consultation is successful when:
- ✅ Codex provides clear recommendation
- ✅ All options have risk assessment
- ✅ Implementation guidance provided
- ✅ User has sufficient information to decide
- ✅ Potential pitfalls identified
📝 Best Practices
Before Consultation
- Clearly define the problem and constraints
- Research existing patterns in codebase
- Identify at least 2 viable options
- Document non-functional requirements
During Consultation
- Wait for complete Codex response
- Validate recommendations against project context
- Identify any missed considerations
- Synthesize with project-specific knowledge
After Consultation
- Document the decision and rationale
- Update architecture documentation if needed
- Share decision with team
- Reference consultation in implementation
⚠️ Important Reminders
- Use early - Consult before writing code, not after
- Be specific - Provide detailed context and constraints
- Consider context - Codex doesn't know your project specifics
- Final decision - Human makes the final call, not AI
- Document - Record the decision for future reference
- Output in Japanese - All user-facing text in Japanese
Didn't find tool you were looking for?