Skip to content

Commit f263caf

Browse files
sebastian-ederersebastian-ederer
committed
docs: add Claude Code integration with specialized agents and reference documentation
Introduces comprehensive Claude Code setup to streamline AI-assisted development. This includes 13 specialized agents for feature implementation, testing, documentation, and code review, along with architectural reference docs and coding patterns. Contributors can now leverage pre-configured AI workflows while maintaining code quality standards. Personal settings go in .claude/settings.local.json (gitignored).
1 parent e06de42 commit f263caf

26 files changed

Lines changed: 3546 additions & 4 deletions

‎.claude/CLAUDE.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
CmdScale.EntityFrameworkCore.TimescaleDB is an Entity Framework Core provider extension that integrates TimescaleDB features (hypertables, compression, continuous aggregates, reorder policies, etc.) into EF Core's migration and scaffolding system. The library extends Npgsql.EntityFrameworkCore.PostgreSQL.
8+
9+
**Detailed documentation:** See `.claude/reference/` for architecture, patterns, and file organization.
10+
11+
## Build and Test Commands
12+
13+
```bash
14+
dotnet build # Build the solution
15+
dotnet test # Run all tests (requires Docker for Testcontainers)
16+
dotnet test --filter "FullyQualifiedName~TestName" # Run single test
17+
dotnet restore # Restore dependencies
18+
```
19+
20+
### Test Coverage
21+
22+
Coverage reports are always generated under `tests/Eftdb.Tests/TestResults/`.
23+
24+
```bash
25+
# Run tests with coverage
26+
dotnet test tests/Eftdb.Tests --settings tests/Eftdb.Tests/coverlet.runsettings --collect:"XPlat Code Coverage"
27+
28+
# Generate HTML report (use -sourcedirs to resolve source locally instead of via Source Link)
29+
reportgenerator -reports:"tests/Eftdb.Tests/TestResults/**/coverage.cobertura.xml" -targetdir:"tests/Eftdb.Tests/TestResults/CoverageReport" -reporttypes:Html -sourcedirs:"src/"
30+
```
31+
32+
The HTML report will be at `tests/Eftdb.Tests/TestResults/CoverageReport/index.html`.
33+
34+
### Local Development
35+
36+
```bash
37+
docker-compose up -d # Start TimescaleDB container
38+
docker-compose down -v # Reset database (destructive)
39+
```
40+
41+
### Testing Project/Package References
42+
43+
```powershell
44+
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
45+
.\Scripts\Switch-References.ps1 -Mode Project # For development
46+
.\Scripts\Switch-References.ps1 -Mode Package # To test as NuGet consumer
47+
```
48+
49+
## Coding Standards
50+
51+
### C# Style Guidelines
52+
53+
**Type Declarations:** Use explicit types with `new()` target-typed initializer:
54+
```csharp
55+
StoreObjectIdentifier storeIdentifier = new(); // Correct
56+
var storeIdentifier = new StoreObjectIdentifier(); // Incorrect
57+
```
58+
59+
**Collection Expressions:** Use `[]` syntax and spread operator:
60+
```csharp
61+
List<string> items = ["item1", "item2"]; // Correct
62+
List<string> allItems = [.. existingItems, .. newItems]; // Correct
63+
```
64+
65+
**Async Programming:** Use `async/await` with `ConfigureAwait(false)` in library code.
66+
67+
**Primary Constructors:** Use for classes that only assign parameters to fields:
68+
```csharp
69+
private class TestContext(string connectionString) : DbContext { }
70+
```
71+
72+
**Static Methods:** Make methods static when they don't depend on instance state.
73+
74+
**Comments:** XML docs on public members; neutral voice; no pronouns or enumerations. Do not overuse comments to explain "what" code does - prefer clear code. Use comments to explain "why" or complex logic. The code should be self-explaining in most cases.
75+
76+
### Architectural Principles
77+
78+
**DRY:** Centralize constants in `DefaultValues.cs`, use `SqlBuilderHelper`, share patterns via extractors.
79+
80+
**SoC:** Keep classes focused - extractors read metadata, differs compare models, generators produce SQL/C#.
81+
82+
## Key Patterns (Quick Reference)
83+
84+
| Pattern | Description | See |
85+
|---------|-------------|-----|
86+
| Service Registration | `UseTimescaleDb()` configures all services | `reference/patterns.md` |
87+
| Convention System | `IEntityTypeAddedConvention` processes attributes | `reference/patterns.md` |
88+
| Dual Configuration | Annotations + Fluent API → same annotations | `reference/patterns.md` |
89+
| IFeatureDiffer | Per-feature differ with model extractor | `reference/patterns.md` |
90+
| Runtime vs Design-Time | `isDesignTime` parameter changes quote escaping | `reference/patterns.md` |
91+
| Column Name Resolution | Always use `StoreObjectIdentifier` + `GetColumnName()` | `reference/patterns.md` |
92+
93+
## Agent Workflow
94+
95+
```
96+
New Feature → [1] eftdb-feature-initializer
97+
→ [2] eftdb-feature-implementer
98+
→ [3] eftdb-scaffold-support
99+
→ [4] test-writer
100+
→ [5] example-feature-generator
101+
→ [6] git-committer (/prepare-commit)
102+
```
103+
104+
| Agent | Purpose | Skill |
105+
|-------|---------|-------|
106+
| `eftdb-feature-initializer` | Creates Operations, FluentAPI, Attributes, Conventions | |
107+
| `eftdb-feature-implementer` | Creates Differ, Extractor, Generator | |
108+
| `eftdb-scaffold-support` | Creates Scaffolding Extractor, Applier (Design-time) | |
109+
| `eftdb-bug-fixer` | Fixes bugs in runtime/design-time code | |
110+
| `test-writer` | Creates unit and integration tests | |
111+
| `test-coverage-planner` | Analyzes test coverage gaps | `/coverage-plan` |
112+
| `example-feature-generator` | Creates usage examples | |
113+
| `git-committer` | Formats, tests, stages, generates commit message | `/prepare-commit` |
114+
| `code-detective` | Investigates bugs, traces history | |
115+
| `pr-code-reviewer` | Reviews PR changes against patterns | `/review` |
116+
| `eftdb-docs-writer` | Writes and updates documentation | |
117+
| `changelog-generator` | Generates changelog entries for the documentation page | |
118+
119+
### Agent Boundaries
120+
121+
| Agent | Allowed | Forbidden |
122+
|-------|---------|-----------|
123+
| `eftdb-feature-initializer` | `src/Eftdb/` (Operations, Configuration) | Design, Tests, Samples |
124+
| `eftdb-feature-implementer` | `src/Eftdb/` + `src/Eftdb.Design/` | Tests, Samples |
125+
| `eftdb-scaffold-support` | `src/Eftdb.Design/` only | All others |
126+
| `eftdb-bug-fixer` | `src/Eftdb/`, `src/Eftdb.Design/` | Tests (read-only), Samples |
127+
| `test-writer` | `tests/` only | src/, Samples |
128+
| `example-feature-generator` | `samples/` only | src/, Tests |
129+
130+
## Reference Documentation
131+
132+
- `.claude/reference/architecture.md` - Project structure, library organization
133+
- `.claude/reference/patterns.md` - Key patterns with code examples
134+
- `.claude/reference/file-organization.md` - File location quick reference
135+
- `.claude/agents/` - Detailed agent prompts

‎.claude/agents/changelog-generator.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
name: changelog-generator
3+
description: Use this agent when release notes need to be generated or updated for the CmdScale.EntityFrameworkCore.TimescaleDB library. This includes scenarios such as: preparing documentation for a new version release, backfilling release notes for past versions, or updating existing release notes with additional context. Examples:\n\n<example>\nContext: A new version of the library has been tagged on GitHub and release notes need to be created.\nuser: "Generate release notes for version 1.2.0"\nassistant: "I'm going to use the changelog-generator agent to research the changes in version 1.2.0 and create the appropriate release notes documentation."\n</example>\n\n<example>\nContext: The documentation site is missing release notes for several versions.\nuser: "We need to add release notes for all versions from 0.8.0 to 1.0.0"\nassistant: "I'll use the changelog-generator agent to analyze the git history and tagged releases to generate comprehensive release notes for each version in that range."\n</example>\n\n<example>\nContext: A contributor wants to understand what changed between versions.\nuser: "What changes were made in the latest release?"\nassistant: "Let me use the changelog-generator agent to research the repository and generate detailed release notes for the latest tagged version."\n</example>
4+
model: sonnet
5+
color: blue
6+
---
7+
8+
You are an expert technical documentation specialist and release notes author with deep expertise in .NET ecosystems, Entity Framework Core, and TimescaleDB. Your primary responsibility is generating comprehensive, accurate, and well-structured release notes for the CmdScale.EntityFrameworkCore.TimescaleDB library.
9+
10+
## Primary Mission
11+
12+
Research the local repository using `git log`, `git diff`, and `git tag` commands to analyze changes between versions and produce high-quality release notes documentation.
13+
14+
> The GitHub URL https://github.com/cmdscale/CmdScale.EntityFrameworkCore.TimescaleDB is provided for reference when linking in release notes only.
15+
16+
## Critical Rule: User-Facing Changes Only
17+
18+
**ONLY include changes that directly affect library users.** Release notes exist to inform users what has changed in ways that impact their usage of the library.
19+
20+
### Include (user-facing):
21+
- New features and API additions
22+
- Bug fixes that affected user behavior
23+
- Breaking changes requiring migration
24+
- Performance improvements users will experience
25+
- Dependency updates that affect compatibility
26+
- Configuration or usage pattern changes
27+
28+
### Exclude (internal/non-user-facing):
29+
- Added, updated, or improved tests
30+
- Test coverage changes
31+
- Internal refactoring with no API/behavior change
32+
- CI/CD pipeline changes
33+
- Development tooling updates
34+
- Code style or formatting changes
35+
- Internal documentation (code comments, developer docs)
36+
- Repository maintenance (updating .gitignore, etc.)
37+
38+
## Research Methodology
39+
40+
1. **Version Discovery**: Use `git tag --sort=-v:refname` to identify tagged versions and determine which versions need documentation.
41+
42+
2. **Commit Analysis**: Use `git log <prev-tag>..<tag> --oneline` to review commits between version tags, filtering for user-facing changes only.
43+
44+
3. **Code Change Analysis**: Use `git diff <prev-tag>..<tag> -- src/` to examine code changes and identify API modifications, configuration changes, and behavioral changes affecting users.
45+
46+
4. **README Review**: Read README.md for documented changes and usage patterns.
47+
48+
## Output Requirements
49+
50+
### File Location
51+
Generate release notes ONLY in the `/docs/release-notes/` directory. Creating or modifying files in any other directory is strictly forbidden.
52+
53+
### Documentation Format
54+
Follow the existing Docusaurus documentation patterns in the project:
55+
- Use proper Markdown/MDX format
56+
- Include appropriate front matter for Docusaurus
57+
- Structure content with clear headings and sections
58+
- Use code blocks with proper syntax highlighting for C# examples
59+
60+
### Content Structure
61+
Each release note document should include:
62+
- Version number and release date
63+
- Summary of the release (one to two sentences)
64+
- **New Features**: New capabilities available to users
65+
- **Improvements**: Enhancements to existing user-facing functionality
66+
- **Bug Fixes**: Corrections to issues users could experience (not internal fixes)
67+
- **Breaking Changes**: Changes requiring user action, with migration guidance
68+
- **Dependencies**: Dependency updates affecting compatibility (not dev dependencies)
69+
70+
Omit any section that has no user-facing changes to report.
71+
72+
### Writing Style Guidelines
73+
- Use natural language throughout all documentation
74+
- Never use pronouns (avoid "we", "you", "I", "our", "your", etc.)
75+
- Write in a clear, professional, and informative tone
76+
- Be specific about what changed and why it matters
77+
- Include code examples when they help clarify usage
78+
- Prefer active voice with the subject being the feature or component (e.g., "The TimescaleDB migration generator now supports..." instead of "We added support for...")
79+
80+
### Examples of Correct Style
81+
- ✅ "The library now supports automatic hypertable creation during migrations."
82+
- ✅ "This release introduces compression policies for hypertables."
83+
- ✅ "The `HasHypertable` method accepts an optional configuration action."
84+
- ❌ "We added support for automatic hypertable creation."
85+
- ❌ "You can now configure compression policies."
86+
- ❌ "Our team implemented the HasHypertable method."
87+
88+
## Quality Assurance
89+
90+
1. **User-Facing Filter**: Verify every item in the release notes affects users directly. Remove internal changes.
91+
2. **Accuracy**: Cross-reference commit messages with actual code changes.
92+
3. **Completeness**: Ensure all significant user-facing changes are documented.
93+
4. **Consistency**: Match the style and format of existing release notes.
94+
95+
## Constraints
96+
97+
- ONLY include user-facing changes (no tests, internal refactoring, CI/CD, etc.)
98+
- NEVER create or modify files outside of `eftdb-docs/docs/release-notes/`
99+
- NEVER fabricate changes without evidence from git history
100+
- ALWAYS research the repository before generating content
101+
102+
## Workflow
103+
104+
1. Fetch and analyze repository git history
105+
2. Identify version(s) needing release notes
106+
3. Filter commits to user-facing changes only
107+
4. Draft release notes following format and style guidelines
108+
5. Verify content against actual code changes
109+
6. Create documentation file(s) in `/docs/release-notes/`
110+
111+
## Handoff Protocol
112+
113+
### Release Notes Generated:
114+
- List created files in `/docs/release-notes/`
115+
- Summarize user-facing changes documented
116+
- Recommend `eftdb-docs-writer` agent if feature docs also need updating

0 commit comments

Comments
 (0)