docs: add .agents/ AI-native knowledge base and slim CLAUDE.md#301
Merged
Conversation
Make the repo AI-native: give agents an accurate, navigable knowledge base so sessions start with the right mental model instead of stale prose. - Add .agents/ with an index README + 12 focused, agent-facing docs: architecture, adding-a-new-api, api-catalog, serialization, observability, testing, dependency-injection, build-release-ci, public-api, conventions, known-issues. Each is grounded in real path:symbol references and links to the canonical human docs rather than duplicating them. - Rewrite CLAUDE.md as a lean entry point (30-second architecture, the commands used most, build/release rules, and a routing table into .agents/). - Fix stale framework/architecture drift in .claude/commands/*, docs/index.md, PULL_REQUEST_TEMPLATE.md, and CONTRIBUTING.md: target frameworks are netstandard2.0;net8.0;net10.0, the entry point is the instance-based GoogleMapsClient (no static facade), and serialization is System.Text.Json. Docs only — no production code changes. Tech-debt surfaced during the audit is logged in .agents/known-issues.md and tracked in #292-#300.
🔬 TestGlance✅ 249 passed across 1 job — 95.8% · ⏱️ 11.2s
🟡 build — details✅ 249 passed · ⏭️ 11 skipped vs
Updated 2026-06-14T15:06:00.033Z |
They wrapped single trivial dotnet commands (build/format/pack/restore/test) with no project-specific logic, duplicating CLAUDE.md and .agents/, and had already gone stale (wrong TFMs, Newtonsoft, broken test filter).
The catalog was written before #283/#287/#288 landed and listed only 12 of the 19 services on IGoogleMapsClient. Adds the Roads (SnapToRoads, NearestRoads, SpeedLimits), Solar (BuildingInsights, DataLayers, GeoTiff) and Aerial View (sub-API) services with correct verbs and base classes, and corrects the signing section: Roads/Solar are GET on MapsBaseRequest, so verb no longer implies signability — the base class does.
- api-catalog: PlaceDetailsNew and PlacePhoto are GET, not POST (they override only GetUri(); GetRequestBody() returns null -> engine GETs). Refine the signing section's verb lists and add a Places mixed-verb gotcha. - architecture/CLAUDE: MapsAPIGenericEngine is internal abstract (static methods), not a static class. - architecture: IGoogleMapsClient now exposes 19 service properties (18 IEngineFacade + the AerialView sub-API), not 12. - build-release-ci: default push/PR CI tests net10.0 only; net8.0 is workflow_dispatch-gated. - serialization/known-issues: DurationJsonConverter does null-check its reflected members; reword B3 to the real issue (reflect-by-name + silent partial objects). UnixTimeConverter is one-way (DateTime -> Unix).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes the repo AI-native: a lean
CLAUDE.mdentry point that routes into a new curated.agents/knowledge base, plus fixes to stale docs that were actively misleading (removed-in-2.0 static facade, wrong target frameworks, Newtonsoft references). Docs only — no production code changes.Related issue
n/a. Tech debt surfaced during the audit is filed separately as #292–#300 (all labelled
tech-debt) and logged in.agents/known-issues.md.Changes
.agents/— indexREADME.md(router) + 12 focused, agent-facing docs:architecture,adding-a-new-api,api-catalog,serialization,observability,testing,dependency-injection,build-release-ci,public-api,conventions,known-issues. Each is grounded in realpath:symbolreferences and links to the canonical human docs rather than duplicating them.CLAUDE.mdinto a lean entry point: 30-second architecture, the commands used in most sessions, the rules that break the build/release, and a routing table into.agents/..claude/commands/{format,pack,restore,test}.md,docs/index.md,PULL_REQUEST_TEMPLATE.md,CONTRIBUTING.md): target frameworks arenetstandard2.0;net8.0;net10.0; the entry point is the instance-basedGoogleMapsClient/IGoogleMapsClient(no static facade); serialization isSystem.Text.Json; corrected the test command (realBillablegating, not a brokenTestCategory!=Integrationfilter).Test plan
Documentation-only change — no
.cs/.csproj/workflow/script files were touched (verified viagit status), so the build and test suite are structurally unaffected. Validation performed:CLAUDE.mdand.agents/README.mdresolve to existing files.net6.0/net7.0/net481/net462/net60) is clean except intentional "what was dropped/dead" mentions in the new docs.CLAUDE.md+.agents/README.mdcorrectly routed common tasks (adding an API, observability, billable tests) and stated the entry point / TFMs / no-static-facade accurately.Checklist
dotnet format— n/a, no C# changed.dotnet test— n/a, docs-only; no code paths affected.