Communitygithub.com

Codebase-Architektur verbessern

Erkunde eine Codebasis, um Möglichkeiten für architektonische Verbesserungen zu finden, mit Fokus auf bessere Testbarkeit durch Vertiefung flacher Module. Verwende dies, wenn der Nutzer die Architektur verbessern, Refactoring-Möglichkeiten finden, eng gekoppelte Module konsolidieren oder eine Codebasis KI-navigierbarer machen möchte.

Was ist Codebase-Architektur verbessern?

Diese Fähigkeit (Skill) ermöglicht es einem KI-Agenten, eine Codebasis systematisch auf architektonische Reibungspunkte zu untersuchen und Verbesserungen vorzuschlagen, die auf dem Konzept tiefer Module (Deep Modules) von John Ousterhout basieren. Ein tiefes Modul hat eine kleine Schnittstelle, die eine große Implementierung verbirgt, was die Testbarkeit und KI-Navigation verbessert. Der Skill beginnt mit einer organischen Erkundung der Codebasis, notiert Fälle von flachen Modulen, engen Kopplungen und schwer testbaren Bereichen und präsentiert dann eine Liste von Kandidaten für eine Vertiefung. Der Nutzer wählt einen Kandidaten aus, woraufhin der Agent das Problemfeld erklärt und parallel mehrere radikal unterschiedliche Schnittstellen-Designs durch Sub-Agenten entwerfen lässt. Abschließend wird eine Empfehlung ausgesprochen und ein GitHub-Issue (Refactoring-RFC) erstellt. Unterstützt wird der Skill durch eine Referenzdatei (REFERENCE.md), die Abhängigkeitskategorien und eine Issue-Vorlage enthält.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/cdcoonce/Portfolio_Website/tree/HEAD/.claude/skills/improve-codebase-architecture

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht Codebase-Architektur verbessern?

Erkunde eine Codebasis, wie es eine KI tun würde, decke architektonische Reibung auf, entdecke Möglichkeiten zur Verbesserung der Testbarkeit und schlage Modulvertiefungs-Refactorings als GitHub-Issue-RFCs vor.

Ein tiefes Modul (John Ousterhout, „A Philosophy of Software Design“) hat eine kleine Schnittstelle, die eine große Implementierung verbirgt. Tiefe Module sind testbarer, KI-navigierbarer und ermöglichen Tests an der Grenzfläche statt im Inneren.

Prozess

1. Erkunde die Codebase

Verwende das Agent-Tool mit subagent_type=Explore, um die Codebase natürlich zu durchsuchen. Folge KEINEN starren Heuristiken – erkunde organisch und notiere, wo du auf Reibung stößt:

  • Wo erfordert das Verständnis eines Konzepts das Springen zwischen vielen kleinen Dateien?
  • Wo sind Module so flach, dass die Schnittstelle fast so komplex ist wie die Implementierung?
  • Wo wurden reine Funktionen nur aus Gründen der Testbarkeit extrahiert, aber die eigentlichen Fehler verstecken sich darin, wie sie aufgerufen werden?
  • Wo erzeugen eng gekoppelte Module Integrationsrisiken in den Nähten zwischen ihnen?
  • Welche Teile der Codebasis sind ungetestet oder schwer zu testen?

Die Reibung, die du erfährst, IST das Signal.

2. Präsentiere Kandidaten

Präsentiere eine nummerierte Liste von Vertiefungsmöglichkeiten. Zeige für jeden Kandidaten:

  • Cluster: Welche Module/Konzepte sind beteiligt
  • Warum sie gekoppelt sind: Gemeinsame Typen, Aufrufmuster, Mitbesitz eines Konzepts
  • Abhängigkeitskategorie: Siehe REFERENCE.md für die vier Kategorien
  • Testauswirkung: Welche vorhandenen Tests würden durch Boundary-Tests ersetzt

Schlage noch keine Schnittstellen vor. Frage den Nutzer: „Welche davon möchtest du erkunden?“

3. Nutzer wählt einen Kandidaten

4. Rahme das Problemfeld ein

Bevor du Sub-Agenten startest, schreibe eine nutzerorientierte Erklärung des Problemfelds für den gewählten Kandidaten:

  • Die Einschränkungen, die jede neue Schnittstelle erfüllen müsste
  • Die Abhängigkeiten, auf die sie angewiesen wäre
  • Eine grobe, illustrative Codeskizze, um die Einschränkungen konkret zu machen – dies ist kein Vorschlag, sondern nur eine Möglichkeit, die Einschränkungen zu verankern

Zeige dies dem Nutzer und fahre dann sofort mit Schritt 5 fort. Der Nutzer liest und denkt über das Problem nach, während die Sub-Agenten parallel arbeiten.

5. Entwerfe mehrere Schnittstellen

Starte 3+ Sub-Agenten parallel mit dem Agent-Tool. Jeder muss eine radikal andere Schnittstelle für das vertiefte Modul erstellen.

Gib jedem Sub-Agenten ein separates technisches Briefing (Dateipfade, Kopplungsdetails, Abhängigkeitskategorie, was verborgen wird). Dieses Briefing ist unabhängig von der nutzerorientierten Erklärung in Schritt 4. Gib jedem Agenten eine andere Design-Einschränkung:

  • Agent 1: „Minimiere die Schnittstelle – strebe maximal 1-3 Einstiegspunkte an“
  • Agent 2: „Maximiere Flexibilität – unterstütze viele Anwendungsfälle und Erweiterungen“
  • Agent 3: „Optimiere für den häufigsten Aufrufer – mach den Standardfall trivial“
  • Agent 4 (falls zutreffend): „Entwirf nach dem Ports & Adapters-Muster für grenzüberschreitende Abhängigkeiten“

Jeder Sub-Agent gibt aus:

  1. Schnittstellensignatur (Typen, Methoden, Parameter)
  2. Nutzungsbeispiel, das zeigt, wie Aufrufer es verwenden
  3. Welche Komplexität es intern verbirgt
  4. Abhängigkeitsstrategie (wie Abhängigkeiten behandelt werden – siehe REFERENCE.md)
  5. Kompromisse

Präsentiere die Entwürfe nacheinander und vergleiche sie dann in Prosa.

Nach dem Vergleich gib deine eigene Empfehlung: welcher Entwurf deiner Meinung nach am stärksten ist und warum. Wenn Elemente verschiedener Entwürfe gut zusammenpassen, schlage einen Hybriden vor. Sei meinungsstark – der Nutzer möchte eine klare Einschätzung, nicht nur ein Menü.

6. Nutzer wählt eine Schnittstelle (oder akzeptiert die Empfehlung)

7. Erstelle GitHub-Issue

Erstelle ein Refactoring-RFC als GitHub-Issue mit gh issue create. Verwende die Vorlage in REFERENCE.md. Bitte den Nutzer NICHT um Überprüfung vor der Erstellung – erstelle es einfach und teile die URL.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

cdcoonce/Portfolio_Website

Git commit workflow with enforced conventional commit style. Use when Claude needs to stage and commit changes, craft commit messages, or the user asks to commit, make a commit, or save their work. Ensures consistent commit message format, proper scoping, and atomic commits across the project.

cdcoonce/Portfolio_Website

AI-powered code quality analysis for Python, Markdown, and Mermaid diagrams. Use this skill when: (1) reviewing code for quality issues, (2) checking Python files for PEP8 violations, unused code, missing type hints, docstring problems, complexity issues, or potential runtime errors, (3) validating Markdown documentation for broken links, heading structure, or formatting issues, (4) validating Mermaid diagram syntax, (5) the user asks for a "code review" or "quality check", (6) analyzing code snippets pasted in conversation, or (7) suggesting and applying fixes for code quality issues.

cdcoonce/Portfolio_Website

Deploy the portfolio chat agent Lambda function to AWS. Use when the user asks to deploy, redeploy, push to Lambda, update the chat agent, or after updating context files or lambda_function.py. Rebuilds the knowledge base, packages dependencies, and deploys to AWS Lambda.

cdcoonce/Portfolio_Website

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

cdcoonce/Portfolio_Website

Orchestrate the full GitHub-issues-driven development lifecycle. 7-phase pipeline from brainstorm through PR with state tracking and cross-conversation resume. Use when user says "dev cycle", "development workflow", "full development pipeline", or invokes /dev-cycle.

cdcoonce/Portfolio_Website

Production Python coding standards with automatic version detection (3.10-3.13). Use when writing, reviewing, or refactoring Python to ensure adherence to modern type syntax, LBYL exception handling, pathlib operations, ABC-based interfaces, and production-tested patterns. Not Dagster-specific - applies to any Python project.

cdcoonce/Portfolio_Website

Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.

cdcoonce/Portfolio_Website

GitHub CLI (gh) integration for managing issues, pull requests, branches,

cdcoonce/Portfolio_Website

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

cdcoonce/Portfolio_Website

CEO/founder-mode plan review. Rethink the problem, find the 10-star product, challenge premises, expand scope when it creates a better product. Three modes: SCOPE EXPANSION (dream big), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials). Use when the user asks for a plan review, CEO review, mega review, or wants a plan challenged/stress-tested before implementation.

cdcoonce/Portfolio_Website

Break a PRD into independently-grabbable GitHub issues using tracer-bullet vertical slices. Use when user wants to convert a PRD to issues, create implementation tickets, or break down a PRD into work items.

cdcoonce/Portfolio_Website

Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices, saved as a local Markdown file in docs/plans/. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions "tracer bullets".

cdcoonce/Portfolio_Website

Generate or update the `.claude/docs/project.md` file that gives Claude project-specific context. Use this skill when the user asks to create, update, regenerate, or refresh project context, or says things like "update project.md", "generate project context", "this repo needs a project.md", or "Claude doesn't know about this project". Also trigger when onboarding Claude to a new repository for the first time.

cdcoonce/Portfolio_Website

Generate comprehensive, high-quality README.md files for code repositories. Use this skill whenever the user asks to create, write, generate, update, or improve a README for any project or repository. Also trigger when the user says things like "document this project", "write docs for this repo", "this repo needs a README", "help me onboard developers to this codebase", or asks for project documentation in markdown. Even if the user just says "README" or "readme" in the context of a codebase, use this skill.

cdcoonce/Portfolio_Website

Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.

cdcoonce/Portfolio_Website

Set up pre-commit hooks for the current repo. Use when user wants to add pre-commit hooks, configure commit-time linting, formatting, type checking, or testing. Triggers on "pre-commit", "git hooks", "linting hooks", or /setup-pre-commit.

cdcoonce/Portfolio_Website

Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.

cdcoonce/Portfolio_Website

Triage a bug or issue by exploring the codebase to find root cause, then create a GitHub issue with a TDD-based fix plan. Use when user reports a bug, wants to file an issue, mentions "triage", or wants to investigate and plan a fix for a problem.

cdcoonce/Portfolio_Website

Rewrites the prose sections of wiki pages in-place. Reads source files to understand current context, then updates only the content inside <!-- claude:prose --> ... <!-- claude:prose:end --> markers. Never touches <!-- generated:start --> ... <!-- generated:end --> blocks. Supports targeting a single page with /update-wiki {PageName}.

cdcoonce/Portfolio_Website

Create a PRD through user interview, codebase exploration, and module design, then submit as a GitHub issue. Use when user wants to write a PRD, create a product requirements document, or plan a new feature.

Verwandte Skills