If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/thangchung/clean-code-dotnet shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 2mo ago
• 12 active contributors
• MIT licensed
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live thangchung/clean-code-dotnet repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/thangchung/clean-code-dotnet.

What it runs against: a local clone of thangchung/clean-code-dotnet — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in thangchung/clean-code-dotnet | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 102 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of thangchung/clean-code-dotnet. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/thangchung/clean-code-dotnet.git
#   cd clean-code-dotnet
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of thangchung/clean-code-dotnet and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "thangchung/clean-code-dotnet(\\.git)?\\b" \\
  && ok "origin remote is thangchung/clean-code-dotnet" \\
  || miss "origin remote is not thangchung/clean-code-dotnet (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Program.cs" \\
  && ok "Program.cs" \\
  || miss "missing critical file: Program.cs"
test -f "cheatsheets/Clean-Code-V2.4.pdf" \\
  && ok "cheatsheets/Clean-Code-V2.4.pdf" \\
  || miss "missing critical file: cheatsheets/Clean-Code-V2.4.pdf"
test -f "cheatsheets/README.md" \\
  && ok "cheatsheets/README.md" \\
  || miss "missing critical file: cheatsheets/README.md"
test -f ".gitignore" \\
  && ok ".gitignore" \\
  || miss "missing critical file: .gitignore"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 102 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~72d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/thangchung/clean-code-dotnet"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A curated educational guide documenting Clean Code principles from Robert C. Martin's book, adapted specifically for C# and .NET/.NET Core developers. It provides concrete before/after code examples covering naming conventions, SOLID principles, testing patterns, error handling, and formatting—helping .NET teams write more readable, maintainable, and refactorable code. Single-level repo structure: README.md and README-zh.md contain the primary content organized by topic (Naming, Variables, Functions, SOLID, Testing, etc.), with supporting cheatsheets in /cheatsheets/ (Clean-Code-V2.4.pdf, Clean-Architecture-V1.0.pdf) and a minimal Program.cs entry point. All content is narrative with embedded code examples rather than a code library.

.NET and .NET Core developers at all levels who want to improve code quality and follow established software engineering best practices. Specifically useful for junior developers learning clean code standards and senior engineers establishing team coding guidelines.

This is a mature educational reference project with 208 lines of C# examples across well-organized sections. It lacks build artifacts or CI/CD setup (no .github/workflows visible), suggesting it's a documentation-focused repo rather than an actively developed library. The presence of cheatsheets and comprehensive README indicates stable, reference-quality content suitable for learning.

Low risk for consumption since this is a documentation/education repo with no runtime dependencies. However, it appears to be a single-maintainer project (thangchung) with no visible test suite or CI pipeline to validate code examples. Code snippets are illustrative only and not executed, so there's no guarantee examples compile or follow latest .NET standards.

No active development signals are visible from the file list provided. This appears to be a stable educational resource maintained for reference rather than actively developed with recent commits or feature work.

Clone the repository and read: git clone https://github.com/thangchung/clean-code-dotnet.git && cd clean-code-dotnet && cat README.md. No build or install step is needed—this is a documentation-first project.

Daily commands: This is not an executable project. Read the README.md directly in GitHub or your editor. The Program.cs file is minimal and not required for using the resource.

• README.md — Primary documentation detailing clean code principles adapted for .NET, including naming, functions, SOLID, testing, and error handling—essential onboarding for all contributors.
• Program.cs — Entry point demonstrating clean code practices in C#; shows practical application of the repo's core principles.
• cheatsheets/Clean-Code-V2.4.pdf — Reference cheatsheet for clean code conventions and guidelines that inform all code examples and documentation in the repo.
• cheatsheets/README.md — Index and guide to cheatsheet resources; directs contributors to core reference materials for architectural and code quality standards.
• .gitignore — Defines which files should not be tracked; critical for maintaining repo cleanliness and avoiding accidental commits of build artifacts.

• README.md (Markdown, GitHub Pages rendering) — Primary teaching document covering naming conventions, variable declarations, function design, object-oriented principles, SOLID, testing, concurrency, error handling, formatting, and commenting for .NET.
  • Failure mode: If outdated, developers may learn obsolete practices; if unclear, principles are misunderstood and not applied.
• Program.cs (C#, .NET runtime) — Practical code examples demonstrating the clean code principles documented in README; serves as executable reference and validation that examples compile correctly.
  • Failure mode: If examples are incorrect or outdated, developers lose confidence in the guidance and may not apply principles correctly.
• Cheatsheets (PDF) (PDF format, Adobe/native viewers) — Quick-reference visual summaries of clean code and architecture patterns; enable offline learning and printing for desk-side reference.
  • Failure mode: If cheatsheets diverge from README or become outdated, developers reference conflicting information.
• GitHub Sponsorship & Social Links (GitHub, Twitter, Medium) — Community engagement channels (.github/FUNDING.yml) linking to maintainer's blog and Twitter for deeper discussions and ongoing support.
  • Failure mode: If links are broken or unmaintained, community loses avenue for questions and engagement.

• Repository (GitHub) → Developer's Local Machine — Clone or download of repository containing all documentation, examples, and cheatsheets.
• README.md → Developer's Understanding — Sequential reading of principles (naming → variables → functions → SOLID → testing) builds conceptual knowledge.
• Program.cs Examples → Developer's Code Implementation — Practical code examples in C# are adapted and applied to the developer's own .NET projects.
• Cheatsheets → Quick Reference During Development — Developers consult PDF cheatsheets during coding to quickly validate principles and patterns.
• Developer Feedback → GitHub Issues & Pull Requests — Community contributions improve and update documentation, examples, and translations based on real-world usage.

Add a New Clean Code Topic Section

1. Create a new markdown section in README.md with heading, code examples (bad vs. good), and explanation. (README.md)
2. Add corresponding practical examples in Program.cs demonstrating the principle in working C# code. (Program.cs)
3. Update the Table of Contents in README.md to include the new section. (README.md)

Translate Documentation to a New Language

1. Create a new README file (e.g., README-es.md for Spanish) with full translation of README.md. (README-es.md)
2. Link the new translation from the main README.md in a language selection section. (README.md)

Add a New Reference Cheatsheet

1. Create a new PDF cheatsheet summarizing a clean code topic and save to cheatsheets/ directory. (cheatsheets/Clean-{Topic}-V1.0.pdf)
2. Add a link and brief description in the cheatsheets README. (cheatsheets/README.md)
3. Reference the new cheatsheet in the main README.md under the Cheatsheets section. (README.md)

• Markdown (README.md/README-zh.md) — Lightweight, version-controllable, renders natively on GitHub for easy accessibility and community contribution.
• C# with Program.cs — Demonstrates clean code principles in the target language (.NET), making examples immediately applicable to the intended audience.
• PDF Cheatsheets — Offline-accessible, printable reference material for quick lookups during development without requiring internet access.
• Git + GitHub — Enables community contributions, version control of documentation, and leverages GitHub's native rendering for maximum discoverability.

• Educational resource rather than enforced linting/tooling framework

  • Why: Allows flexibility and broad applicability across different .NET projects and team contexts.
  • Consequence: Relies on developer discipline to apply principles; does not automatically prevent violations.

• Single Program.cs file for examples rather than full project structure

  • Why: Keeps the repo lightweight and focused on principles rather than production-ready application code.
  • Consequence: Examples are illustrative rather than complete, production-grade implementations.

• PDF cheatsheets alongside Markdown documentation

  • Why: Provides offline reference and print-friendly format for quick lookups during coding sessions.
  • Consequence: Maintenance burden of keeping multiple formats in sync; potential for version skew.

• Does not provide automated code analysis or linting tools
• Does not enforce clean code rules at build or CI/CD time
• Not a complete .NET application framework or production boilerplate
• Does not include test examples or test suite demonstrating testing principles
• Not a language specification or C# compiler—purely educational reference

• Avg cyclomatic complexity: ~2 — Repository is primarily educational documentation with minimal executable code complexity; Program.cs contains simple illustrative examples rather than complex algorithms or logic.
• Largest file: README.md (800 lines)
• Estimated quality issues: ~1 — Repository has high quality by design (it teaches clean code); minor issue is lack of automated testing or

• Incomplete or missing examples for certain principles (Medium) — README.md: Some SOLID principles or concurrency patterns may have limited practical examples in Program.cs, leaving developers uncertain how to implement them.
• No automated testing or linting validation (Medium) — Repository structure: Program.cs examples are not validated by unit tests or CI/CD linters, so example code correctness is not machine-verified.
• Potential version drift between PDF cheatsheets and Markdown docs (Low) — cheatsheets/ vs README.md: Multiple documentation formats (Markdown + PDFs) create risk that principles diverge if one is updated without synchronizing the other.

• README.md (Documentation organization) — Large single documentation file covering many topics (naming, functions, SOLID, testing, concurrency, error handling, comments) may be difficult to navigate and update; could benefit from splitting into topic-specific pages.
• Program.cs (Code organization) — All examples consolidated into one file rather than organized by topic; as examples grow, file becomes harder to navigate and maintain.
• Cheatsheet maintenance (Process/tooling) — PDFs require manual creation and updates; no automated generation from source, creating manual maintenance burden for synchronization with Markdown.

No hidden traps—this is a documentation repo. No runtime dependencies, no build tools required, no services to configure. Code examples are illustrative and not executed; they may not compile or reflect the latest C# version. Expect content to lag behind latest .NET releases since it's manually maintained.

• SOLID Principles — Core to the repo's guidance on class design; understanding Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion is essential for writing maintainable .NET code
• Clean Code (Robert C. Martin's paradigm) — The entire repo is an adaptation of Martin's Clean Code book principles for .NET; understanding his philosophy on naming, functions, error handling, and concurrency is foundational
• Naming conventions and semantics — The repo's first and largest section shows how variable, method, and class names must reveal intent and reduce cognitive load in .NET code
• Hungarian Notation (anti-pattern) — Explicitly called out in the repo as an outdated naming practice; understanding why prefixing type information (e.g., iCount) is harmful helps junior devs recognize and avoid legacy patterns
• Concurrency patterns in .NET — The Concurrency section addresses async/await, threading, and thread-safety specific to .NET; critical for writing non-blocking, scalable server code
• Error handling and exception design — The repo covers .NET-specific exception handling patterns and when to use exceptions vs. result types; essential for writing resilient applications
• Clean Architecture — Referenced via cheatsheet (Clean-Architecture-V1.0.pdf); extends Clean Code principles to system design, separation of concerns, and layering in .NET applications

• ryanmcdermott/clean-code-javascript — Original inspiration for this .NET adaptation; covers same principles (SOLID, naming, functions) but for JavaScript ecosystem
• jupeter/clean-code-php — Parallel Clean Code guide for PHP developers; demonstrates the pattern of adapting Robert Martin's principles to different languages
• ardalis/CleanArchitecture — Companion .NET project by Steve Smith (Ardalis) providing working sample code and project templates for Clean Architecture in C#
• dotnet-architecture/eShopOnWeb — Reference implementation by Microsoft showing Clean Architecture and SOLID principles applied in a real .NET web application
• microsoft/dotnet — Official .NET runtime and tooling; necessary context for understanding C# language versions and framework capabilities mentioned throughout clean-code-dotnet

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add C# code examples to each Clean Code section in README.md

The README.md has a Table of Contents listing major sections (Naming, Variables, Functions, Objects and Data Structures, Classes, SOLID, Testing, Concurrency, Error Handling, Formatting, Comments) but the snippet shows the content is cut off. Each section should include before/after C# code examples demonstrating anti-patterns and clean code alternatives. This makes the repo immediately actionable for .NET developers rather than just theoretical.

• [ ] Expand README.md with complete 'Naming' section including 3-5 C# code examples (bad vs good naming conventions)
• [ ] Add 'Variables' section with examples of magic numbers, type clarity, and variable scope in C#
• [ ] Add 'Functions' section with examples of function length, parameters, and single responsibility in C# methods
• [ ] Add remaining sections (Objects/Classes/SOLID/Testing/etc) with concrete C# examples
• [ ] Ensure each section has at least 2 before/after code snippets

Create Program.cs example application demonstrating Clean Code principles

Program.cs exists but appears to be empty or minimal. A complete, well-structured sample application (e.g., a simple domain service with proper SOLID principles, clean naming, error handling) would serve as a reference implementation. This transforms the repo from educational theory into a working template developers can learn from and extend.

• [ ] Design a simple domain (e.g., Order Management, User Management) that covers multiple Clean Code principles
• [ ] Implement proper folder structure (Domain/, Application/, Infrastructure/) following Clean Architecture
• [ ] Add examples covering: naming conventions, SOLID principles, dependency injection, error handling, and unit testability
• [ ] Create accompanying test project (Tests/Program.Tests.cs) with examples of clean testing practices
• [ ] Document the example in README.md with explanations of architectural choices

Add GitHub Actions workflow for automated code quality checks

The repo lacks CI/CD automation. Given that clean-code-dotnet is specifically about code quality standards, it should demonstrate those standards through automated tooling. A workflow checking code formatting (StyleCop), static analysis (SonarQube/Roslyn), and building the sample code would validate the examples and signal quality to contributors.

• [ ] Create .github/workflows/dotnet-quality.yml with steps for: dotnet build, StyleCop analysis, and unit tests
• [ ] Add .editorconfig file to the root enforcing C# naming/formatting conventions discussed in the README
• [ ] Add a GitHub Action that runs on pull requests to validate all new examples compile and pass linting
• [ ] Document the quality standards in CONTRIBUTING.md (new file)

• Add C# 11+ feature examples (records, primary constructors, file-scoped types) to the Naming and Classes sections to keep advice current with modern language capabilities.
• Expand the Testing section with concrete xUnit/NUnit examples and async testing patterns specific to .NET, as current coverage is minimal.
• Create a .github/workflows/lint-markdown.yml CI check to validate code snippet syntax consistency and ensure all Bad/Good examples follow the established <details> + heading + code-block format.

This is an educational repository focused on Clean Code concepts and best practices for .NET development. It is not a production application but rather a reference/learning resource. No critical security vulnerabilities were identified in the provided codebase snapshot. The repository contains documentation, cheatsheets, and code examples for teaching purposes. Minor recommendations for enhancement are noted below.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.