docs: add AI agent operating guides and workflow SOPs across all projects - #40
Merged
Conversation
- Add a repository-level CLAUDE.md defining architecture boundaries and layering rules - Document non-negotiable de-branding requirements and release workflow conventions - Establish coding standards, fragile-zone handling expectations, and response-format guidance
…asks - Add standardized procedures for field/template additions, pipeline bug fixes, and release cuts - Define step-by-step branch, testing, documentation, de-branding, and PR requirements per workflow - Establish a cross-cutting readiness gate to enforce build quality, test health, API docs, and commit/PR conventions
- Add facade-specific CLAUDE guidance covering contracts, exception boundaries, DI constraints, and fragile caching behavior - Add Axlis.ORM workflow SOPs for facade method pairing, DI registration changes, and cache/lazy-loader modifications - Document naming drift and reinforce current extension method conventions for consumer-facing setup
…mentation - Define Abstractions-layer architectural constraints, compatibility requirements, and dependency boundaries - Document rules for adding and changing contracts, including breaking-change handling and downstream impact checks - Add no-op implementation guidance and clarify responsibilities for contract placement and XML documentation quality
- Add project-scoped CLAUDE documentation defining Core layer responsibilities, dependency boundaries, and static loader constraints - Document fragile-zone handling for ItemConverter, AxesAdapter, and ExtendedItem with explicit module-spec references - Add Core workflow SOPs for field types, built-in templates, and high-risk model conversion or lazy-loading changes
- Add project-scoped CLAUDE documentation defining transport and service responsibilities, exception behavior, and batch-query invariants - Add GraphQL workflow SOPs for introducing new service operations, evolving batch query handling, and updating transport error classification - Document architectural constraints around raw HttpClient usage, no third-party GraphQL clients, and caching ownership boundaries
- Document the lazy-loading architecture across AxesAdapter, ExtendedItem, and IItemLazyLoader - Define invariants and failure-mode hazards including static ambient loader state, silent exception swallowing, and sync-over-async risks - Add modification guidance and a verification checklist for tests and behavioral contract changes
- Document ItemConverter responsibilities, recursion model, and conversion invariants - Capture circular-reference handling, depth asymmetry, and field-loading flag semantics - Add known limitations, change guidelines, and verification checklist for regression-safe updates
- Document cache manager purpose, external cache-service dependency assumptions, and key behavioral invariants - Define dual/triple indexing, null-miss non-caching, case-sensitivity risks, TTL semantics, and invalidation boundaries - Add modification guidance and verification checklist to protect cache behavior regressions
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.
Establishes a comprehensive set of AI agent governance and workflow documentation across the entire Axlis repository, covering the root, all four source projects, and the three documented fragile zones.
What was added
CLAUDE.md— repository-wide AI agent operating guide defining the core role, architecture constraints, dependency rules, coding standards, Git/PR conventions, de-branding requirements, and response formatting rules for any AI agent working in this repo.WORKFLOWS.md— repository-wide SOPs for recurring engineering tasks (branching, commits, releases, NuGet publishing, etc.).src/Axlis.ORM/CLAUDE.mdandWORKFLOWS.md— project-scoped guidance for the facade layer, including the dual API contract (Clean / Rich), caching integration, DI wiring, and exception-handling responsibility at the top of the stack.src/Axlis.ORM.Abstractions/CLAUDE.mdandWORKFLOWS.md— guidance enforcing thenetstandard2.0+net8.0dual-target, zero-dependency floor, and the compatibility contract for downstream .NET Framework consumers.src/Axlis.ORM.Core/CLAUDE.mdandWORKFLOWS.md— guidance for the domain/conversion layer, flaggingItemConverter,AxesAdapter, and lazy-loading infrastructure as fragile zones requiring test coverage before any change is considered done.src/Axlis.ORM.GraphQL/CLAUDE.mdandWORKFLOWS.md— guidance for the transport/query layer, includingHttpGraphQLTransport,SitecoreService, andGraphQLQueryBuilderboundaries.src/Axlis.ORM.Core/ItemConverter.md— module specification for the recursive GraphQL JSON →Itemgraph converter, documenting the circular-reference guard and field-type mapping contract.src/Axlis.ORM.Core/AxesLazyLoading.md— module specification for the axes lazy-loading subsystem, documenting the static ambient_lazyLoaderfield,IItemLazyLoadercontract, and the silent-swallow risk inAxesAdapter.TryUpdateAxes().src/Axlis.ORM/Caching/CacheManager.md— module specification forSitecoreItemCacheManager, documenting the dual-index (ID + path) strategy, null-miss non-caching behavior, and eviction semantics.Why
These files provide AI agents (and human contributors) with the architectural context, hard constraints, and fragile-zone guardrails needed to operate safely in this codebase without requiring a full read of the source tree on every session. They do not modify any compiled or shipped code.