From 8edb769196e59f6f4e164f7f4b0e5701efd4f591 Mon Sep 17 00:00:00 2001 From: beo3000 Date: Wed, 24 Dec 2025 10:50:01 +0100 Subject: [PATCH] update Claude MDs --- .claude/commands/branch.md | 18 ++++ .claude/commands/commit.md | 15 ++++ .claude/commands/implement.md | 87 +++++++++++++++++++ .claude/commands/review.md | 74 ++++++++++++++++ CLAUDE.md | 6 +- docs/development_guidelines.md | 152 +++++++++++++++++++++++++++++++++ 6 files changed, 348 insertions(+), 4 deletions(-) create mode 100644 .claude/commands/branch.md create mode 100644 .claude/commands/commit.md create mode 100644 .claude/commands/implement.md create mode 100644 .claude/commands/review.md create mode 100644 docs/development_guidelines.md diff --git a/.claude/commands/branch.md b/.claude/commands/branch.md new file mode 100644 index 0000000..dc1f4ac --- /dev/null +++ b/.claude/commands/branch.md @@ -0,0 +1,18 @@ +--- +allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git checkout:*), Bash(git switch:*), AskUserQuestion +description: Check git status and create a new branch +--- + +## Context + +- Current git status: !`git status --porcelain` +- Current branch: !`git branch --show-current` +- Existing branches: !`git branch -a` + +## Your task + +1. Check if working directory is clean (no uncommitted changes from git status above) +2. If there are uncommitted changes, warn user and stop +3. If clean, ask user for new branch name using AskUserQuestion +4. Create and switch to the new branch using `git checkout -b ` +5. Confirm success with current branch info diff --git a/.claude/commands/commit.md b/.claude/commands/commit.md new file mode 100644 index 0000000..d2e608f --- /dev/null +++ b/.claude/commands/commit.md @@ -0,0 +1,15 @@ +--- +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*) +description: Create a git commit +--- + +## Context + +- Current git status: !`git status` +- Current git diff (staged and unstaged changes): !`git diff HEAD` +- Current branch: !`git branch --show-current` +- Recent commits: !`git log --oneline -10` + +## Your task + +Based on the above changes, create a single git commit. \ No newline at end of file diff --git a/.claude/commands/implement.md b/.claude/commands/implement.md new file mode 100644 index 0000000..4a00684 --- /dev/null +++ b/.claude/commands/implement.md @@ -0,0 +1,87 @@ +--- +allowed-tools: Bash(git *), Read, Write, Edit, Glob, Grep, Bash(dotnet build:*), Bash(dotnet test:*), Bash(dotnet ef:*), AskUserQuestion +description: Identify the next step in the plan, and start implementing this phase (project) +--- + +## Context + +- Implementation Plan: !`cat docs/IMPLEMENTATION_PLAN.md | head -400` +- Current branch: !`git branch --show-current` +- Git status: !`git status --porcelain` + +## Your Task - Implement Next Phase + +Follow these steps in order: + +### Step 1: Identify Next Phase +- Read `docs/IMPLEMENTATION_PLAN.md` +- Find the first row in the table with `☐` (open status) +- Extract: Phase ID (e.g., C1), Bereich, Beschreibung +- Read the detailed phase section (e.g., "### **Phase C1: ...**") +- Summarize what needs to be implemented + +### Step 2: Create Git Branch +- Check git status is clean (no uncommitted changes) +- If dirty, warn user and STOP +- Create branch: `git checkout -b feature/-` + - Example: `feature/c1-club-state-fluxor` +- Confirm branch created + +### Step 3: Implement Phase +- Follow the detailed phase description from the plan +- Create/modify files as specified +- Follow project conventions from CLAUDE.md: + - Clean Architecture layers + - XML documentation in English + - Fluxor pattern for state (Actions/Reducers/Effects) + - MudBlazor for UI components +- Build after each major change: `dotnet build` +- Commit logical chunks with descriptive messages + +### Step 4: Review Implementation +Perform code review checklist: + +**Code Conventions:** +- [ ] Follows Clean Architecture layer separation +- [ ] XML documentation on public members (English) +- [ ] Proper namespacing and file organization + +**Error Handling:** +- [ ] Loading states in Blazor components +- [ ] Null checks where appropriate +- [ ] Validation on user inputs + +**Accessibility:** +- [ ] MudBlazor components use proper labels +- [ ] Form fields have Label properties + +**Tests:** +- [ ] Run: `dotnet test test/Koogle.Tests` +- [ ] New functionality has tests (if applicable) + +**Security:** +- [ ] Authorization attributes on protected resources +- [ ] Input validation on boundaries + +**Build:** +- [ ] `dotnet build` succeeds without errors/warnings + +### Step 5: Mark Phase Complete +- Edit `docs/IMPLEMENTATION_PLAN.md` +- In the overview table, change the phase row from `☐` to `✓` +- Example: `| ☐ | **C1** |` becomes `| ✓ | C1 |` +- Remove bold formatting when marking complete +- Commit: "Complete phase : " + +### Step 6: Summary +Report: +- Phase completed +- Files created/modified +- Any issues encountered +- Next phase preview (what comes after) + +## Important Notes +- If build fails, fix before proceeding +- If tests fail, fix before marking complete +- Ask user for clarification if phase description is ambiguous +- Do NOT skip steps - follow the workflow strictly diff --git a/.claude/commands/review.md b/.claude/commands/review.md new file mode 100644 index 0000000..420b58f --- /dev/null +++ b/.claude/commands/review.md @@ -0,0 +1,74 @@ +--- +allowed-tools: Bash(git diff:*), Bash(git log:*), Bash(git status:*), Bash(dotnet build:*), Bash(dotnet test:*), Read, Grep, Glob, Edit +description: Comprehensive code review of recent changes +--- + +## Context + +- Current branch: !`git branch --show-current` +- Recent commits on this branch: !`git log --oneline -10` +- Changed files: !`git diff --name-only HEAD~5 2>/dev/null || git diff --name-only` +- Staged changes: !`git diff --cached --stat` + +## Code Review Checklist + +Perform a comprehensive code review of recent changes. For each category, check the changed files and report findings. + +### 1. Code Conventions +- Follows Clean Architecture layer separation (Domain → Application → Infrastructure → Web) +- Proper namespacing and file organization +- XML documentation on public members (English) +- Consistent naming (PascalCase for public, camelCase for private) +- No magic strings/numbers - use constants or enums +- DTOs in Application layer, Entities in Domain + +### 2. Error Handling & Loading States +- Try-catch with proper exception types +- Blazor components handle loading states (`IsLoading` patterns) +- Null checks where appropriate +- Validation on user inputs +- Graceful degradation on failures + +### 3. Accessibility (a11y) +- MudBlazor components use `aria-*` attributes where needed +- Proper `Label` properties on form fields +- Color contrast considerations +- Keyboard navigation support +- Screen reader compatibility + +### 4. Test Coverage +- New public methods have unit tests +- Tests in `test/Koogle.Tests` follow existing patterns +- Use FluentAssertions and Moq +- Edge cases covered +- Run: `dotnet test test/Koogle.Tests` + +### 5. Security +- No SQL injection (use parameterized queries/EF Core) +- No XSS vulnerabilities (Blazor auto-escapes, but check `MarkupString`) +- Authorization attributes on protected endpoints +- Sensitive data not logged +- Input validation on boundaries +- CSRF protection maintained + +### 6. Performance +- No N+1 query patterns (use `.Include()` appropriately) +- Async/await used correctly +- No blocking calls in async context +- Large collections paginated +- Expensive operations cached where appropriate + +### 7. Documentation +- CLAUDE.md updated if new patterns introduced +- Implementation plan updated if phase completed +- Public APIs documented with XML comments + +## Your Task + +1. Review all changed files against each checklist category +2. Build the project: `dotnet build` +3. Run tests: `dotnet test test/Koogle.Tests` +4. Report findings per category with file:line references +5. Suggest fixes for any issues found +6. If new patterns discovered, update CLAUDE.md accordingly +7. Provide overall assessment: PASS / PASS WITH NOTES / NEEDS CHANGES diff --git a/CLAUDE.md b/CLAUDE.md index 7978d27..8755d65 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +The development guidelines to consider are descibed in [docs/development_guidelines.md](./docs/development_guidelines.md) + ## Project Overview Blazor Server app (.NET 9.0) with Clean Architecture: Domain, Application, Infrastructure, Web layers. Uses ASP.NET Core Identity with dual DbContext pattern (AppDbContext for domain, AppIdentityDbContext for auth), MudBlazor UI, and Fluxor state management. @@ -26,10 +28,6 @@ The name for the App is KOOGLE. Koogle is an app for club management. - primarily Bowling clubs (Kegelclub / Kegelvereine) - In German "Kegeln" is a bit different to bowling - maybe in future also for darts, soccer betting pools, Leisure groups, Sport clubs, etc. -## Implementation Plan - -- alle Implementierung sollen mit xmldoc in englischer Spreche kommentiert werden - **Phase 1 MVP:** See [docs/IMPLEMENTATION_PLAN.md](./docs/IMPLEMENTATION_PLAN.md) - 23 granular phases (A1-F3) - Foundation → Clubs → Users → Persons → Days → Dashboard diff --git a/docs/development_guidelines.md b/docs/development_guidelines.md new file mode 100644 index 0000000..9bc734e --- /dev/null +++ b/docs/development_guidelines.md @@ -0,0 +1,152 @@ +# 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` see [docs/IMPLEMENTATION_PLAN.md](./docs/IMPLEMENTATION_PLAN.md) + +```markdown +## 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 \ No newline at end of file