AIが書いたプロジェクトコードの信頼性を高めるグローバル・キュー・ワード

を受けて Claude Code 歌で応える GitHub Copilot ラージ・ランゲージ・モデル（LLM）コーディング・アシスタントの普及に伴い、ソフトウェア開発のワークフローは変革期を迎えている。これらのツールは、アイデアから実現までの時間を劇的に短縮し、時間がかかるために保留されていたプロジェクトを迅速に進めることを可能にしている。

しかし、AIが生成したコードは、しばしば正しさや効率性に問題がある。成功の鍵は、明確で効率的な共同作業規範を確立することにある。AIに明確な開発ガイドラインのセットを提供することは、AIが高品質で一貫性があり、保守可能なコードを出力することを保証する最も効果的な方法の1つである。

このガイドブックは、AIとの各インタラクションに文脈を提供する「グローバル・プロファイル」として機能し、特定の開発哲学、プロセス、技術標準に従うよう誘導する。

以下は、保存してそのまま使える個人用の「グローバル・プロキシ・ガイド」です。に保存することをお勧めします。 ~/.claude/CLAUDE.md 必要なときに素早く呼び出せるようにするためだ。

パーソナル "グローバル "エージェントガイド

本書は、AIコーディングアシスタントと連携するための中核となるガイドラインである。

# Development Guidelines
## Philosophy
### Core Beliefs
- **Incremental progress over big bangs** - Small changes that compile and pass tests
- **Learning from existing code** - Study and plan before implementing
- **Pragmatic over dogmatic** - Adapt to project reality
- **Clear intent over clever code** - Be boring and obvious
### Simplicity Means
- Single responsibility per function/class
- Avoid premature abstractions
- No clever tricks - choose the boring solution
- If you need to explain it, it's too complex
## Process
### 1. Planning & Staging
Break complex work into 3-5 stages. Document in `IMPLEMENTATION_PLAN.md`:
```
## Stage N: [Name]
**Goal**: [Specific deliverable]
**Success Criteria**: [Testable outcomes]
**Tests**: [Specific test cases]
**Status**: [Not Started|In Progress|Complete]
```
- Update status as you progress
- Remove file when all stages are done
### 2. Implementation Flow
1. **Understand** - Study existing patterns in codebase
2. **Test** - Write test first (red)
3. **Implement** - Minimal code to pass (green)
4. **Refactor** - Clean up with tests passing
5. **Commit** - With clear message linking to plan
### 3. When Stuck (After 3 Attempts)
**CRITICAL**: Maximum 3 attempts per issue, then STOP.
1. **Document what failed**:
- What you tried
- Specific error messages
- Why you think it failed
2. **Research alternatives**:
- Find 2-3 similar implementations
- Note different approaches used
3. **Question fundamentals**:
- Is this the right abstraction level?
- Can this be split into smaller problems?
- Is there a simpler approach entirely?
4. **Try different angle**:
- Different library/framework feature?
- Different architectural pattern?
- Remove abstraction instead of adding?
## Technical Standards
### Architecture Principles
- **Composition over inheritance** - Use dependency injection
- **Interfaces over singletons** - Enable testing and flexibility
- **Explicit over implicit** - Clear data flow and dependencies
- **Test-driven when possible** - Never disable tests, fix them
### Code Quality
- **Every commit must**:
- Compile successfully
- Pass all existing tests
- Include tests for new functionality
- Follow project formatting/linting
- **Before committing**:
- Run formatters/linters
- Self-review changes
- Ensure commit message explains "why"
### Error Handling
- Fail fast with descriptive messages
- Include context for debugging
- Handle errors at appropriate level
- Never silently swallow exceptions
## Decision Framework
When multiple valid approaches exist, choose based on:
1. **Testability** - Can I easily test this?
2. **Readability** - Will someone understand this in 6 months?
3. **Consistency** - Does this match project patterns?
4. **Simplicity** - Is this the simplest solution that works?
5. **Reversibility** - How hard to change later?
## Project Integration
### Learning the Codebase
- Find 3 similar features/components
- Identify common patterns and conventions
- Use same libraries/utilities when possible
- Follow existing test patterns
### Tooling
- Use project's existing build system
- Use project's test framework
- Use project's formatter/linter settings
- Don't introduce new tools without strong justification
## Quality Gates
### Definition of Done
- [ ] Tests written and passing
- [ ] Code follows project conventions
- [ ] No linter/formatter warnings
- [ ] Commit messages are clear
- [ ] Implementation matches plan
- [ ] No TODOs without issue numbers
### Test Guidelines
- Test behavior, not implementation
- One assertion per test when possible
- Clear test names describing scenario
- Use existing test utilities/helpers
- Tests should be deterministic
## Important Reminders
**NEVER**:
- Use `--no-verify` to bypass commit hooks
- Disable tests instead of fixing them
- Commit code that doesn't compile
- Make assumptions - verify with existing code
**ALWAYS**:
- Commit working code incrementally
- Update plan documentation as you go
- Learn from existing implementations
- Stop after 3 failed attempts and reassess

なぜこのガイドが効果的なのか？

上記のガイドラインをコンテキストとしてAIに提供することは、AIに明確な「ゲームのルール」を設定することに等しい。

• 開発哲学の設定ガイドの冒頭にある「核となる信念」と「シンプルさ」の定義は、過剰に設計された "派手な "コードよりも、シンプルで実用的でメンテナンスが容易なコードを優先するようAIを導く。核となる信念」と「シンプルさ」の定義は、過剰に設計された「派手な」コードよりも、シンプルで実用的でメンテナンスしやすいコードを生成するようAIを導く。
• 標準化されたワークフローよりIMPLEMENTATION_PLAN.mdこのプロセスは、「AI」ルールの策定から、テスト駆動開発（TDD）の実施プロセス、困難な状況に陥ったときの対処法に至るまで、AIが複雑なタスクで脱線するのを防ぐための明確な行動ステップを提供する。特に、「3回試行したら一時停止」ルールは、AIが間違った経路で多くの時間と計算資源を浪費するのを効果的に防ぐ。
• 技術基準の設定アーキテクチャの原則、コード品質、エラー処理に関するセクションでは、AIに厳しい制約を設定している。これにより、AIが生成するコードがコンパイルされるだけでなく、プロジェクトの全体的なアーキテクチャ要件と品質要件を満たすことが保証される。
• 意思決定の基礎を提供する意思決定フレームワーク」のセクションでは、テストしやすさ、読みやすさ、その他の観点からAIに選択肢を評価させ、複数の実装パスが存在する場合には、それらを理解させる。これによって開発者は、理解不能なブラックボックスに直面することなく、AIの技術的選択を素早く検討することができる。
• 最終的な品質を重視した完了定義チェックリストは、各成果物がプロジェクトの仕様に対して完全にテストされ、検証されていることを確認するための品質ゲートウェイとして機能します。

最終的には、開発者はAIによって生成されたコードの一行一行に責任を負うことになる。人間によるレビューは、必要不可欠な最終防衛ラインなのだ。このガイドの最大の価値は、AIのアウトプットを人間の専門家の考え方とエンジニアリング基準に近づけることで、レビューと統合のプロセスを大幅に簡素化することだ。

中国のキュー

# 开发指南
## 开发哲学
### 核心信念
- **渐进式进展优于颠覆式创新** - 提交微小、可通过测试的变更。
- **从现有代码中学习** - 在动手前，先研究和规划。
- **务实胜过教条** - 适应项目现实。
- **清晰意图胜过巧妙代码** - 保持代码的枯燥和直白。
### 简洁的含义
- 每个函数/类只承担单一职责。
- 避免过早的抽象。
- 不耍小聪明 - 选择最“无聊”的解决方案。
- 如果你的代码需要解释才能看懂，那它就太复杂了。
## 工作流程
### 1. 规划与分阶段
将复杂的工作分解为 3-5 个阶段，并在 `IMPLEMENTATION_PLAN.md` 文件中记录：
```markdown
## 阶段 N: [阶段名称]
**目标**: [具体的可交付成果]
**成功标准**: [可测试的结果]
**测试**: [具体的测试用例]
**状态**: [未开始 | 进行中 | 已完成]
```
- 随着你的进展更新状态。
- 所有阶段完成后，删除此文件。
### 2. 实现流程
1.  **理解** - 研究代码库中现有的模式。
2.  **测试** - 先编写测试（红灯）。
3.  **实现** - 编写最少的代码以通过测试（绿灯）。
4.  **重构** - 在测试通过的前提下清理代码。
5.  **提交** - 提交时附带清晰的、关联到计划的消息。
### 3. 陷入困境时（尝试3次后）
**至关重要**：每个问题最多尝试 3 次，然后停下来。
1.  **记录失败之处**：
    -   你尝试了什么。
    -   具体的错误信息。
    -   你认为失败的原因。
2.  **研究替代方案**：
    -   寻找 2-3个 类似的实现。
    -   注意它们使用的不同方法。
3.  **反思根本问题**：
    -   当前的抽象层次是否正确？
    -   这个问题能否拆解成更小的问题？
    -   是否有一个从根本上更简单的办法？
4.  **尝试不同角度**：
    -   使用不同的库或框架特性？
    -   采用不同的架构模式？
    -   是应该移除抽象，而不是增加抽象？
## 技术标准
### 架构原则
-   **组合优于继承** - 使用依赖注入。
-   **面向接口而非单例** - 保证可测试性和灵活性。
-   **显式优于隐式** - 保持清晰的数据流和依赖关系。
-   **尽可能测试驱动** - 永远不要禁用测试，而是修复它们。
### 代码质量
-   **每一次提交都必须**：
    -   成功编译。
    -   通过所有现有测试。
    -   为新功能包含测试。
    -   遵循项目的格式化/代码规范。
-   **提交之前**：
    -   运行格式化/代码规范检查工具。
    -   自行审查变更。
    -   确保提交消息解释了“为什么”这么做。
### 错误处理
-   用描述性的信息实现快速失败（Fail Fast）。
-   在错误中包含有助于调试的上下文。
-   在适当的层级处理错误。
-   绝不静默地吞掉异常。
## 决策框架
当存在多种有效方法时，基于以下标准进行选择：
1.  **可测试性** - 我能轻松测试这个方案吗？
2.  **可读性** - 六个月后，有人能看懂这段代码吗？
3.  **一致性** - 这是否符合项目的既有模式？
4.  **简洁性** - 这是能解决问题的最简单的方案吗？
5.  **可逆性** - 以后要改动这个决策有多难？
## 项目集成
### 学习代码库
-   找到 3 个类似的功能或组件。
-   识别通用的模式和约定。
-   尽可能使用相同的库和工具。
-   遵循现有的测试模式。
### 工具使用
-   使用项目现有的构建系统。
-   使用项目现有的测试框架。
-   使用项目现有的格式化/代码规范配置。
-   若无充分理由，不要引入新工具。
## 质量门禁
### “完成”的定义
-   [ ] 测试已编写并通过
-   [ ] 代码遵循项目约定
-   [ ] 没有格式化/代码规范工具的警告
-   [ ] 提交消息清晰明确
-   [ ] 实现与计划相符
-   [ ] 没有未关联 issue 编号的 TODO 注释
### 测试准则
-   测试行为，而不是测试实现细节。
-   如有可能，每个测试只包含一个断言。
-   使用清晰的、描述场景的测试名称。
-   使用现有的测试工具和辅助函数。
-   测试应该是确定性的。
## 重要提醒
**绝不**：
-   使用 `--no-verify` 来绕过提交钩子。
-   禁用测试，而不是修复它们。
-   提交无法编译的代码。
-   凭空假设 - 通过现有代码来验证。
**始终**：
-   渐进式地提交可工作的代码。
-   随时更新计划文档。
-   从现有的实现中学习。
-   尝试 3 次失败后停下来重新评估。