|
1 | | -# Conversations |
2 | | -any resulting updates to agents.md should go under the section "## Rules to follow" |
3 | | -When you see a convincing argument from me on how to solve or do something. add a summary for this in agents.md. so you learn what I want over time. |
4 | | -If I say any of the following point, you do this: add the context to agents.md, and associate this with a specific type of task. |
5 | | -if I say "never do x" in some way. |
6 | | -if I say "always do x" in some way. |
7 | | -if I say "the process is x" in some way. |
8 | | -If I tell you to remember something, you do the same, update |
| 1 | +# AGENTS.md |
9 | 2 |
|
| 3 | +Project: ManagedCode.TimeSeries |
| 4 | +Stack: .NET 10 (net10.0) / C# 14 with Nullable + ImplicitUsings; xUnit + Shouldly tests; Orleans serialization adapters; BenchmarkDotNet; coverlet; central package versions via Directory.Packages.props. |
10 | 5 |
|
11 | | -## Rules to follow (SUPER IMPORTANT) |
12 | | -For any code modification task: run dotnet build before applying changes to capture the current error count. After the changes, run dotnet build again and only commit if the error count stays the same or decreases; revert if it increases. |
| 6 | +Follows [MCAF](https://mcaf.managed-code.com/) |
13 | 7 |
|
| 8 | +--- |
14 | 9 |
|
15 | | -# Repository Guidelines |
| 10 | +## Conversations (Self-Learning) |
16 | 11 |
|
17 | | -## Project Structure & Module Organization |
18 | | -- `ManagedCode.TimeSeries/` — core library with accumulators, summers, and shared abstractions. |
19 | | -- `ManagedCode.TimeSeries.Tests/` — xUnit test suite referencing the core project; coverage instrumentation configured via coverlet. |
20 | | -- `ManagedCode.TimeSeries.Orleans/` — Orleans-specific adapters built atop the core types. |
21 | | -- `ManagedCode.TimeSeries.Benchmark/` — BenchmarkDotNet harness for performance tracking, entry point in `Program.cs`. |
22 | | -- `Directory.Build.props` centralizes NuGet metadata, reproducible build settings, and solution-wide assets. |
| 12 | +Learn the user's habits, preferences, and working style. Extract rules from conversations, save to "## Rules to follow", and generate code according to the user's personal rules. |
23 | 13 |
|
24 | | -## Build, Test, and Development Commands |
25 | | -- `dotnet restore` — fetch solution dependencies. |
26 | | -- `dotnet build --configuration Release` — compile all projects and validate analyzers. |
27 | | -- `dotnet test ManagedCode.TimeSeries.Tests/ManagedCode.TimeSeries.Tests.csproj -p:CollectCoverage=true` — run tests with coverlet lcov output (mirrors CI). |
28 | | -- `dotnet run --project ManagedCode.TimeSeries.Benchmark/ManagedCode.TimeSeries.Benchmark.csproj -c Release` — execute benchmarks before publishing performance-sensitive changes. |
29 | | -- `dotnet pack ManagedCode.TimeSeries/ManagedCode.TimeSeries.csproj -c Release` — produce the NuGet package using metadata from `Directory.Build.props`. |
| 14 | +**Update requirement (core mechanism):** |
30 | 15 |
|
31 | | -## Coding Style & Naming Conventions |
32 | | -Target `net9.0` with C# 13, `Nullable` and `ImplicitUsings` enabled; favour modern language features when they improve clarity. Stick to four-space indentation, braces on new lines, PascalCase for types, methods, and public properties, camelCase for locals and parameters, and ALL_CAPS only for constants. Keep namespaces aligned with folder paths under `ManagedCode.TimeSeries`. |
| 16 | +Before doing ANY task, evaluate the latest user message. |
| 17 | +If you detect a new rule, correction, preference, or change → update `AGENTS.md` first. |
| 18 | +Only after updating the file you may produce the task output. |
| 19 | +If no new rule is detected → do not update the file. |
33 | 20 |
|
34 | | -## Testing Guidelines |
35 | | -Use xUnit `[Fact]` and `[Theory]` patterns with Shouldly for assertions; prefer descriptive test method names (`MethodUnderTest_State_Expectation`). Ensure new logic includes coverage and leaves no skipped tests behind; if a skip is unavoidable, document the unblocker in-code. Generate fresh coverage via the command above before opening a PR and verify lcov output lands under `ManagedCode.TimeSeries.Tests/`. |
| 21 | +**When to extract rules:** |
36 | 22 |
|
37 | | -## Commit & Pull Request Guidelines |
38 | | -Follow the repo’s concise commit style (`scope summary` or short imperative lines under ~60 characters, e.g., `bench improve queue path`). Each PR should describe the change, reference related issues, and call out API or serialization impacts. Include evidence of local `dotnet test` runs (and benchmarks when relevant) plus screenshots for user-facing changes. Highlight breaking changes or version bumps so release automation remains accurate. |
| 23 | +- prohibition words (never, don't, stop, avoid) or similar → add NEVER rule |
| 24 | +- requirement words (always, must, make sure, should) or similar → add ALWAYS rule |
| 25 | +- memory words (remember, keep in mind, note that) or similar → add rule |
| 26 | +- process words (the process is, the workflow is, we do it like) or similar → add to workflow |
| 27 | +- future words (from now on, going forward) or similar → add permanent rule |
| 28 | + |
| 29 | +**Preferences → add to Preferences section:** |
| 30 | + |
| 31 | +- positive (I like, I prefer, this is better) or similar → Likes |
| 32 | +- negative (I don't like, I hate, this is bad) or similar → Dislikes |
| 33 | +- comparison (prefer X over Y, use X instead of Y) or similar → preference rule |
| 34 | + |
| 35 | +**Corrections → update or add rule:** |
| 36 | + |
| 37 | +- error indication (this is wrong, incorrect, broken) or similar → fix and add rule |
| 38 | +- repetition frustration (don't do this again, you ignored, you missed) or similar → emphatic rule |
| 39 | +- manual fixes by user → extract what changed and why |
| 40 | + |
| 41 | +**Strong signal (add IMMEDIATELY):** |
| 42 | + |
| 43 | +- swearing, frustration, anger, sarcasm → critical rule |
| 44 | +- ALL CAPS, excessive punctuation (!!!, ???) → high priority |
| 45 | +- same mistake twice → permanent emphatic rule |
| 46 | +- user undoes your changes → understand why, prevent |
| 47 | + |
| 48 | +**Ignore (do NOT add):** |
| 49 | + |
| 50 | +- temporary scope (only for now, just this time, for this task) or similar |
| 51 | +- one-off exceptions |
| 52 | +- context-specific instructions for current task only |
| 53 | + |
| 54 | +**Rule format:** |
| 55 | + |
| 56 | +- One instruction per bullet |
| 57 | +- Tie to category (Testing, Code, Docs, etc.) |
| 58 | +- Capture WHY, not just what |
| 59 | +- Remove obsolete rules when superseded |
| 60 | + |
| 61 | +--- |
| 62 | + |
| 63 | +## Rules to follow (Mandatory, no exceptions) |
| 64 | + |
| 65 | +### Commands |
| 66 | + |
| 67 | +- build: `dotnet build ManagedCode.TimeSeries.slnx --configuration Release` |
| 68 | +- test: `dotnet test ManagedCode.TimeSeries.Tests/ManagedCode.TimeSeries.Tests.csproj --configuration Release` |
| 69 | +- format: `dotnet format ManagedCode.TimeSeries.slnx` |
| 70 | +- coverage: `dotnet test ManagedCode.TimeSeries.Tests/ManagedCode.TimeSeries.Tests.csproj --configuration Release -p:CollectCoverage=true -p:CoverletOutputFormat=lcov` |
| 71 | + |
| 72 | +### Task Delivery (ALL TASKS) |
| 73 | + |
| 74 | +- Architecture-first, no exceptions: always start from `docs/Architecture/Overview.md` to locate modules and boundaries; if it is missing, stop and ask for bootstrap (do not add file-creation logic to AGENTS.md). |
| 75 | +- Git history pattern: commit messages are short, lowercase summaries without conventional prefixes; keep under ~60 chars. |
| 76 | +- Branch naming: only `main` is present; if a branch is needed, use short lowercase names (no new scheme). |
| 77 | +- For code modification tasks: run `dotnet build ManagedCode.TimeSeries.slnx --configuration Release` before changes to capture error count, then run it again after; only commit if the error count stays the same or decreases, otherwise revert. |
| 78 | +- Any AGENTS.md updates from conversation context must be added under "## Rules to follow." |
| 79 | +- Domain context (feature/bug work): this library aggregates events into time-series metrics via accumulators and summers; prioritize low allocations and lock-free paths. |
| 80 | +- After every build you run for a code-change task, run `dotnet format ManagedCode.TimeSeries.slnx`; if formatting changes files, rebuild to confirm the error count still does not increase. |
| 81 | +- The architecture overview must include detailed workflow diagrams and explanations for accumulators and summers so their operation is clear. |
| 82 | +- All public types must remain thread-safe for concurrent reads/writes; add multi-threaded tests to validate this. |
| 83 | +- Fix all build/test warnings before finalizing work. |
| 84 | +- Performance is critical: prefer non-blocking, allocation-conscious patterns; avoid `ToArray()`/sorting in hot paths unless justified. |
| 85 | +- README and docs must use professional tone (no informal phrases like “YouTube-style”). |
| 86 | +- Document time handling as “UTC-normalized”: APIs accept any offset, but values are normalized to UTC internally; avoid phrasing “UTC only.” |
| 87 | +- Ensure public API semantics are reviewed and documented; add XML documentation to public methods/properties. |
| 88 | +- Orleans 9 serialization guidance in docs must match official configuration patterns; do not document unsupported `AddSerializer(...AddConverter...)` usage. |
| 89 | +- Orleans converters must exist for all introduced public time-series collection types (accumulators/summers/groups). |
| 90 | +- When requested, perform a final review pass and report readiness for release. |
| 91 | +- Consider single-threaded Orleans scenarios when choosing concurrent collections; document the rationale for keeping or changing `ConcurrentQueue` and do not weaken thread-safety guarantees. |
| 92 | + |
| 93 | +### Testing |
| 94 | + |
| 95 | +- Tests live in `ManagedCode.TimeSeries.Tests` and use xUnit + Shouldly; helper assertions are in `ManagedCode.TimeSeries.Tests/Assertions/ShouldlyExtensions.cs`. |
| 96 | +- Test files are organized by feature (`AccumulatorsTests`, `SummersTests`, `TimeSeriesBehaviorTests`, `TimeSeriesAdvancedTests`); most tests use `[Fact]`, async tests are acceptable. |
| 97 | +- Avoid skipped tests; if a skip is unavoidable, document the unblocker in-code. |
| 98 | +- Ensure all tests pass after changes; add or expand tests to increase coverage when behavior changes or bugs are fixed. |
| 99 | +- When a review/report lists issues, implement fixes for all listed findings unless explicitly scoped out. |
| 100 | +- Measure code coverage; if it drops below 90%, add tests to restore it (including multi-threaded coverage where appropriate). |
| 101 | + |
| 102 | +### Code Style |
| 103 | + |
| 104 | +- File-scoped namespaces, four-space indentation, braces on new lines. |
| 105 | +- Naming: PascalCase for types/members, `_camelCase` for private fields, `camelCase` for locals/parameters, PascalCase constants. |
| 106 | +- Nullable reference types + implicit usings are enabled (see `Directory.Build.props`); use null-forgiving (`!`) sparingly. |
| 107 | +- `var` is used when the type is obvious; explicit types are used when clarity matters. |
| 108 | +- Target net10.0 / C# 14; prefer new language/runtime features when they improve clarity or reduce allocations. |
| 109 | +- Prefer unsigned numeric types for values that can never be negative; avoid negative sentinel values (use `0` for “unbounded”). |
| 110 | +- Prefer `DateTime.UtcNow` for timestamps unless offset is required; avoid storing offsets in hot paths. |
| 111 | +- Prefer `System.Text.Json` for serialization/deserialization paths. |
| 112 | +- Rename public surface areas when a clearer domain term improves correctness (e.g., “Samples” as time-series samples, not examples). |
| 113 | + |
| 114 | +### Boundaries |
| 115 | + |
| 116 | +- Core lock-free time-series logic in `ManagedCode.TimeSeries/Abstractions`, `ManagedCode.TimeSeries/Accumulators`, and `ManagedCode.TimeSeries/Summers` is performance-critical; avoid adding locks or extra allocations. |
| 117 | +- Orleans serialization adapters in `ManagedCode.TimeSeries.Orleans` are compatibility boundaries; keep converter/surrogate changes backward-compatible. |
| 118 | +- Central build + version config lives in `Directory.Build.props` and `Directory.Packages.props`; change cautiously. |
| 119 | +- Benchmarks in `ManagedCode.TimeSeries.Benchmark` are the performance baseline when optimizing. |
| 120 | +- Favor non-blocking collections and patterns over locking when optimizing concurrency. |
| 121 | + |
| 122 | +--- |
| 123 | + |
| 124 | +## Preferences |
| 125 | + |
| 126 | +### Likes |
| 127 | + |
| 128 | +### Dislikes |
0 commit comments