Globale Stichwörter, die den von der KI geschriebenen Projektcode zuverlässiger machen

im Zuge von Claude Code im Gesang antworten GitHub Copilot Die Arbeitsabläufe bei der Softwareentwicklung verändern sich mit der zunehmenden Beliebtheit von Large Language Model (LLM)-Codierassistenten wie diesen. Diese Werkzeuge haben die Zeit von der Idee bis zur Realisierung drastisch verkürzt, so dass Projekte, die früher aufgrund ihrer zeitaufwändigen Natur auf Eis gelegt wurden, nun schneller vorangetrieben werden können.

KI-generierter Code hat jedoch oft Probleme mit der Korrektheit oder Effizienz. Der Schlüssel zum Erfolg liegt in der Festlegung klarer und effizienter Normen für die Zusammenarbeit. Der KI klare Entwicklungsrichtlinien an die Hand zu geben, ist eine der wirksamsten Methoden, um sicherzustellen, dass sie hochwertigen, konsistenten und wartbaren Code produziert.

Dieser Leitfaden dient als "globales Profil", das den Kontext für jede Interaktion mit der KI liefert und sie anleitet, bestimmte Entwicklungsphilosophien, Prozesse und technische Standards zu befolgen.

Nachstehend finden Sie einen persönlichen "Globalen Proxy-Leitfaden", der gespeichert und direkt verwendet werden kann. Es wird empfohlen, ihn im Verzeichnis ~/.claude/CLAUDE.md Pfad, um sie bei Bedarf schnell abrufen zu können.

Persönlicher "globaler" Agentenführer

Dieses Dokument ist der zentrale Leitfaden für die Zusammenarbeit mit KI-Codierassistenten.

# 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

Warum ist dieser Leitfaden so wirksam?

Der KI die oben genannten Leitlinien als Kontext zur Verfügung zu stellen, ist gleichbedeutend mit der Festlegung klarer "Spielregeln" für sie.

• Festlegung der EntwicklungsphilosophieDie "Grundüberzeugungen" und die Definition von "Einfachheit" am Anfang des Leitfadens führen dazu, dass KI eher einfachen, pragmatischen und leicht zu wartenden Code als übermäßig gestalteten "auffälligen" Code bevorzugt. Die "Grundüberzeugungen" und die Definition von "Einfachheit" leiten die KI dazu an, einfachen, pragmatischen und leicht zu wartenden Code zu generieren, statt übermäßig gestalteten "auffälligen" Code.
• Standardisierter Arbeitsablauf: VonIMPLEMENTATION_PLAN.mdDieser Prozess gibt der KI klare Handlungsschritte vor, die verhindern, dass sie sich bei komplexen Aufgaben verzettelt, von der Formulierung der "KI"-Regeln über die Implementierung der testgetriebenen Entwicklung (TDD) bis hin zu den Bewältigungsstrategien, wenn sie in einer schwierigen Situation stecken bleibt. Insbesondere die Regel "Pause nach drei Versuchen" verhindert wirksam, dass die KI viel Zeit und Rechenressourcen auf dem falschen Weg vergeudet.
• Technische Standards festgelegtIn den Abschnitten über Architekturprinzipien, Codequalität und Fehlerbehandlung werden harte Einschränkungen für AI festgelegt. Dadurch wird sichergestellt, dass der erzeugte Code nicht nur kompiliert wird, sondern auch den allgemeinen Architektur- und Qualitätsanforderungen des Projekts entspricht.
• Bereitstellung einer Grundlage für die EntscheidungsfindungDer Abschnitt "Entscheidungsrahmen" zwingt AI dazu, die Optionen im Hinblick auf Testbarkeit, Lesbarkeit und andere Dimensionen zu bewerten und einen Sinn darin zu sehen, wenn es mehrere Wege zur Implementierung gibt. Dies ermöglicht es Entwicklern, die von AI gewählten Technologien schnell zu überprüfen, anstatt mit einer unverständlichen Blackbox konfrontiert zu werden.
• Der Schwerpunkt wurde auf die endgültige Qualität gelegtDie Checkliste "Definition of Done" dient als Qualitätskontrolle, um sicherzustellen, dass jede Leistung vollständig getestet und anhand der Projektspezifikationen validiert wird.

Letztlich sind die Entwickler immer noch für jede von der KI erzeugte Codezeile verantwortlich. Die menschliche Überprüfung ist eine unverzichtbare letzte Verteidigungslinie. Der größte Wert dieses Leitfadens besteht darin, dass er den Überprüfungs- und Integrationsprozess erheblich vereinfacht, indem er den Output der KI näher an die Denkweise und die technischen Standards menschlicher Experten heranführt.

Chinesische Queues

# 开发指南
## 开发哲学
### 核心信念
- **渐进式进展优于颠覆式创新** - 提交微小、可通过测试的变更。
- **从现有代码中学习** - 在动手前，先研究和规划。
- **务实胜过教条** - 适应项目现实。
- **清晰意图胜过巧妙代码** - 保持代码的枯燥和直白。
### 简洁的含义
- 每个函数/类只承担单一职责。
- 避免过早的抽象。
- 不耍小聪明 - 选择最“无聊”的解决方案。
- 如果你的代码需要解释才能看懂，那它就太复杂了。
## 工作流程
### 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 次失败后停下来重新评估。