Skip to content

Commit 614cc43

Browse files
jennyf19jmprieur
jennyf19
and
jmprieur
authored
add ai assist rules (#3376)
* add ai assist rules * pr feedback * Update .clinerules/idweb-guidelines.md Co-authored-by: Jean-Marc Prieur <[email protected]> --------- Co-authored-by: Jean-Marc Prieur <[email protected]>
1 parent d8397e9 commit 614cc43

5 files changed

Lines changed: 215 additions & 0 deletions

File tree

‎.clinerules/ai-guidelines.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Development Guidelines
2+
3+
This directory contains guidelines for AI assistants:
4+
5+
* [Cline AI Assistant Guidelines](cline-instructions.md) - Guidelines specific to using Cline AI assistant
6+
* [C# Development Guidelines](csharp-guidelines.md) - C# coding standards and best practices
7+
* [IdWeb Guidelines](idweb-guidelines.md) - Guidelines for working with IdWeb components and ecosystem
8+
9+
The guidelines are split into separate files to organize different concerns:
10+
- Cline-specific capabilities and workflows
11+
- C# language-specific standards and practices
12+
- IdWeb-specific development guidelines and best practices

‎.clinerules/cline-instructions.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Cline AI Assistant Guidelines
2+
3+
## Core Principles
4+
5+
* Make changes incrementally and verify each step
6+
* Always analyze existing code patterns before making changes
7+
* Prioritize built-in tools over shell commands
8+
* Follow existing project patterns and conventions
9+
* Maintain comprehensive test coverage
10+
11+
## Tool Usage
12+
13+
### File Operations
14+
* Use `read_file` for examining file contents instead of shell commands like `cat`
15+
* Use `replace_in_file` for targeted, specific changes to existing files
16+
* Use `write_to_file` only for new files or complete file rewrites
17+
* Use `list_files` to explore directory structures
18+
* Use `search_files` with precise regex patterns to find code patterns
19+
* Use `list_code_definition_names` to understand code structure before modifications
20+
21+
### Command Execution
22+
* Use `execute_command` sparingly, preferring built-in file operation tools when possible
23+
* Always provide clear explanations for any executed commands
24+
* Set `requires_approval` to true for potentially impactful operations
25+
26+
## Development Workflow
27+
28+
### Planning Phase (PLAN MODE)
29+
* Begin complex tasks in PLAN mode to discuss approach
30+
* Analyze existing codebase patterns using search tools
31+
* Review related test files to understand testing patterns
32+
* Present clear implementation steps for approval
33+
* Ask clarifying questions early to avoid rework
34+
35+
### Implementation Phase (ACT MODE)
36+
* Make changes incrementally, one file at a time
37+
* Verify each change before proceeding
38+
* Follow patterns discovered during planning phase
39+
* Focus on maintaining test coverage
40+
* Use error messages and linter feedback to guide fixes
41+
42+
## Code Modifications
43+
44+
### General Guidelines
45+
* Follow .editorconfig rules strictly
46+
* Preserve file headers and license information
47+
* Maintain consistent XML documentation
48+
* Respect existing error handling patterns
49+
* Keep line endings consistent with existing files
50+
51+
### Quality Checks
52+
* Verify changes match existing code style
53+
* Ensure test coverage for new code
54+
* Validate changes against project conventions
55+
* Check for proper error handling
56+
* Maintain nullable reference type annotations
57+
58+
## MCP Server Integration
59+
60+
* Use appropriate MCP tools when available for specialized tasks
61+
* Access MCP resources efficiently using proper URIs
62+
* Handle MCP operation results appropriately
63+
* Follow server-specific authentication and usage patterns
64+
65+
## Error Handling
66+
67+
* Provide clear error messages and suggestions
68+
* Handle tool operation failures gracefully
69+
* Suggest alternative approaches when primary approach fails
70+
* Roll back changes if necessary to maintain stability

‎.clinerules/csharp-guidelines.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# C# Development Guidelines
2+
3+
## General
4+
5+
* Always use the latest version C#, currently C# 13 features
6+
* Never change global.json unless explicitly asked to
7+
* Never change package.json or package-lock.json files unless explicitly asked to
8+
* Never change NuGet.config files unless explicitly asked to
9+
10+
## Formatting
11+
12+
* Apply code-formatting style defined in `.editorconfig`
13+
* Prefer file-scoped namespace declarations and single-line using directives
14+
* Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`, `using`, `try`, etc.)
15+
* Ensure that the final return statement of a method is on its own line
16+
* Use pattern matching and switch expressions wherever possible
17+
* Use `nameof` instead of string literals when referring to member names
18+
* Ensure that XML doc comments are created for any public APIs. When applicable, include `<example>` and `<code>` documentation in the comments
19+
20+
### Nullable Reference Types
21+
22+
* Declare variables non-nullable, and check for `null` at entry points
23+
* Always use `is null` or `is not null` instead of `== null` or `!= null`
24+
* Trust the C# null annotations and don't add null checks when the type system says a value cannot be null
25+
26+
### Testing
27+
28+
* We use xUnit SDK v2 for tests
29+
* Emit "Act", "Arrange" or "Assert" comments
30+
* Use Moq 4.14.x for mocking in tests
31+
* Copy existing style in nearby files for test method names and capitalization
32+
33+
## Running tests
34+
35+
* To build and run tests in the repo, run `dotnet test`, you need one solution open, or specify the solution

‎.clinerules/idweb-guidelines.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# IdWeb Guidelines
2+
3+
## Overview
4+
5+
Microsoft Identity Web is a comprehensive authentication and authorization library for ASP.NET Core, OWIN web apps and web APIs, and daemon apps that integrate with the Microsoft identity platform and CIAM or AzureAD B2C. The library provides essential functionality for:
6+
7+
- Web applications that sign in users and optionally call web APIs
8+
- Protected web APIs that may call downstream web APIs
9+
- Daemon applications calling downstream APIs
10+
- Token cache implementations
11+
- Microsoft Graph integration
12+
- Azure SDK integration
13+
14+
Through its modular architecture and extensive features, Microsoft Identity Web simplifies the implementation of identity and access management in modern web applications while maintaining security best practices.
15+
16+
## Repository Structure
17+
18+
### Core Directories
19+
- `/src` - Contains all source code for the Microsoft.Identity.Web packages
20+
- `/tests` - Contains all test projects including unit tests, integration tests and E2E tests
21+
- `/benchmark` - Performance benchmarking tests
22+
- `/build` - Build scripts and configuration
23+
- `/docs` - Documentation and blog posts
24+
- `/ProjectTemplates` - Project templates for various ASP.NET Core scenarios
25+
- `/tools` - Development and configuration tools
26+
27+
### Project Templates
28+
The following templates are provided:
29+
- Blazor Server Web Applications
30+
- Blazor WebAssembly Applications
31+
- Azure Functions
32+
- Razor Pages Web Applications
33+
- ASP.NET Core MVC (Starter Web)
34+
- ASP.NET Core Web API
35+
- Worker Service
36+
- Daemon app
37+
38+
## Shipped DLLs/Packages
39+
40+
The following NuGet packages are shipped as part of Microsoft.Identity.Web:
41+
42+
### Core Packages
43+
- Microsoft.Identity.Web - Core authentication and authorization functionality
44+
- Microsoft.Identity.Web.UI - UI components and controllers for authentication
45+
- Microsoft.Identity.Web.TokenCache - Token cache implementations
46+
- Microsoft.Identity.Web.TokenAcquisition - Token acquisition functionality
47+
- Microsoft.Identity.Web.Certificate - Certificate management and loading
48+
- Microsoft.Identity.Web.Certificateless - Support for certificateless authentication
49+
50+
### Integration Packages
51+
- Microsoft.Identity.Web.Azure - Azure SDK integration support
52+
- Microsoft.Identity.Web.DownstreamApi - Support for calling downstream APIs
53+
- Microsoft.Identity.Web.OWIN - OWIN middleware integration
54+
55+
### Microsoft Graph Packages
56+
- Microsoft.Identity.Web.MicrosoftGraph - Microsoft Graph integration
57+
- Microsoft.Identity.Web.MicrosoftGraphBeta - Microsoft Graph Beta API integration
58+
- Microsoft.Identity.Web.GraphServiceClient - Graph SDK integration
59+
- Microsoft.Identity.Web.GraphServiceClientBeta - Graph Beta SDK integration
60+
61+
### Additional Functionality
62+
- Microsoft.Identity.Web.Diagnostics - Diagnostic and logging support
63+
- Microsoft.Identity.Web.OidcFIC - OpenID Connect Federated Identity Credential support
64+
65+
## Development Guidelines
66+
67+
### Common Development Patterns
68+
- Follow .editorconfig rules strictly
69+
- Ensure proper error handling
70+
- Maintain test coverage for changes
71+
- Document API changes thoroughly
72+
- Keep configuration consistent with project standards
73+
74+
### Testing Requirements
75+
- Include tests for all code changes
76+
- Follow existing test patterns
77+
- Include benchmark tests for performance-sensitive changes
78+
- Verify security implications of changes
79+
80+
### Public API Changes
81+
- The project uses Microsoft.CodeAnalysis.PublicApiAnalyzers (version 3.3.4) to track changes to public APIs
82+
- For any changes to public APIs (classes, interfaces, methods, properties, etc.), you must:
83+
1. Locate the PublicAPI.Unshipped.txt file in the directory of the changed code
84+
2. Include the complete API signature
85+
86+
Example format:
87+
```diff
88+
// Adding new API
89+
+MyNamespace.MyClass.MyNewMethod() -> void
90+
+MyNamespace.MyClass.MyProperty.get -> string
91+
+MyNamespace.MyClass.MyProperty.set -> void
92+
93+
// Removing API
94+
-MyNamespace.MyClass.OldMethod() -> void
95+
```
96+
97+
The analyzer will verify during build that all public API changes are properly documented, and the build will fail if changes are not reflected in PublicAPI.Unshipped.txt.

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Carefully review all markdown documents in the ../.clinerules folder. Those are your custom instructions.

0 commit comments

Comments
 (0)