OpenSkillIndex← back to search
claude-code

Agent-almanac write-claude-md

install
source · Clone the upstream repo
git clone https://github.com/pjt222/agent-almanac
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/de/skills/write-claude-md" ~/.claude/skills/pjt222-agent-almanac-write-claude-md-f55ad2 && rm -rf "$T"
manifest: i18n/de/skills/write-claude-md/SKILL.md
source content

CLAUDE.md schreiben

Eine CLAUDE.md-Datei erstellen, die KI-Assistenten effektiven projektspezifischen Kontext liefert.

Wann verwenden

  • Start eines neuen Projekts mit KI-Assistenten
  • Verbesserung des KI-Assistenten-Verhaltens in einem bestehenden Projekt
  • Dokumentation von Projektkonventionen, Arbeitsablaeufen und Einschraenkungen
  • Integration von MCP-Servern oder Agentendefinitionen in ein Projekt

Eingaben

  • Erforderlich: Projekttyp und Technologiestack
  • Erforderlich: Wichtige Konventionen und Einschraenkungen
  • Optional: MCP-Server-Konfigurationen
  • Optional: Autoren- und Mitwirkendeninformationen
  • Optional: Sicherheits- und Vertraulichkeitsanforderungen

Vorgehensweise

Schritt 1: CLAUDE.md grundlegend erstellen

CLAUDE.md
im Projektstammverzeichnis ablegen:

# Projektname

Kurze Beschreibung des Projekts und seines Zwecks.

## Schnellstart

Wesentliche Befehle fuer die Arbeit an diesem Projekt:

```bash
# Abhaengigkeiten installieren
npm install  # oder renv::restore() fuer R

# Tests ausfuehren
npm test     # oder devtools::test() fuer R

# Build
npm run build  # oder devtools::check() fuer R

Architektur

Wichtige Architekturentscheidungen und in diesem Projekt verwendete Muster.

Konventionen

  • Immer beschreibende Variablennamen verwenden
  • [Sprachspezifischen Stil-Guide] befolgen
  • Tests fuer alle neuen Funktionalitaeten schreiben

**Erwartet:** Eine `CLAUDE.md`-Datei existiert im Projektstammverzeichnis mit mindestens einer Projektbeschreibung, Schnellstart-Befehlen, einer Architekturuebersicht und einem Konventionsabschnitt.

**Bei Fehler:** Falls unklar ist, was einzubeziehen ist, mit nur dem Schnellstart-Abschnitt beginnen, der die drei wichtigsten Befehle enthaelt (installieren, testen, bauen). Die Datei kann inkrementell erweitert werden, waehrend das Projekt reift.

### Schritt 2: Technologiespezifische Abschnitte hinzufuegen

**Fuer R-Pakete**:

```markdown
## Entwicklungsworkflow

```r
devtools::load_all()    # Fuer Entwicklung laden
devtools::document()    # Dokumentation neu generieren
devtools::test()        # Tests ausfuehren
devtools::check()       # Vollstaendige Paketpruefung

Paketstruktur

  • R/
    - Quellcode (eine Funktion pro Datei)
  • tests/testthat/
    - Tests spiegeln R/-Struktur wider
  • vignettes/
    - Ausfuehrliche Dokumentation
  • man/
    - Von roxygen2 generiert (nicht manuell bearbeiten)

Kritische Dateien (nicht loeschen)

  • .Rprofile
    - Sitzungskonfiguration
  • .Renviron
    - Umgebungsvariablen (per git ignoriert)
  • renv.lock
    - Gesperrte Abhaengigkeiten

**Fuer Node.js/TypeScript**:

```markdown
## Stack

- Next.js 15 mit App Router
- TypeScript strict mode
- Tailwind CSS fuer Styling
- Vercel fuer Deployment

## Konventionen

- `@/`-Import-Alias fuer src/-Verzeichnis verwenden
- Server Components standardmaessig, `"use client"` nur wenn noetig
- API-Routen in `src/app/api/`

Erwartet: Technologiespezifische Abschnitte werden hinzugefuegt, die dem tatsaechlichen Stack des Projekts entsprechen — R-Paketstruktur fuer R-Projekte, Node.js-Stack-Details fuer Web-Projekte usw. Befehle und Pfade beziehen sich auf das tatsaechliche Projektlayout.

Bei Fehler: Falls der Stack unbekannt ist, 

package.json
, 
DESCRIPTION
, 
Cargo.toml
oder Aequivalente untersuchen, um die Technologie zu identifizieren und den entsprechenden Abschnitt hinzuzufuegen.

Schritt 3: MCP-Server-Informationen hinzufuegen

## Verfuegbare MCP-Server

### r-mcptools (R-Integration)
- **Zweck**: Verbindung zu R/RStudio-Sitzungen
- **Status**: Konfiguriert
- **Konfiguration**: `claude mcp add r-mcptools stdio "Rscript.exe" -- -e "mcptools::mcp_server()"`

### hf-mcp-server (Hugging Face)
- **Zweck**: KI/ML-Modell- und Datensatzzugriff
- **Status**: Konfiguriert
- **Konfiguration**: `claude mcp add hf-mcp-server -e HF_TOKEN=token -- mcp-remote https://huggingface.co/mcp`

Erwartet: Jeder konfigurierte MCP-Server hat einen Unterabschnitt, der seinen Zweck, Status (konfiguriert/verfuegbar/nicht konfiguriert) und den Befehl zu seiner Einrichtung dokumentiert. Keine tatsaechlichen Token oder Geheimnisse sind enthalten.

Bei Fehler: Falls MCP-Server noch nicht konfiguriert sind, sie als "Verfuegbar" mit Einrichtungsanweisungen anstatt als "Konfiguriert" dokumentieren. Platzhalterwerte wie 

your_token_here
fuer alle Anmeldedaten verwenden.

Schritt 4: Autoreninformationen hinzufuegen

## Autoreninformationen

### Standard-Paket-Autorenschaft
- **Name**: Autorenname
- **E-Mail**: autor@beispiel.de
- **ORCID**: 0000-0000-0000-0000
- **GitHub**: benutzername

Erwartet: Der Autoreninformationsabschnitt enthaelt Name, E-Mail, ORCID (fuer akademische/Forschungsprojekte) und GitHub-Benutzernamen. Fuer R-Pakete entspricht das Format den DESCRIPTION-Datei-Anforderungen.

Bei Fehler: Falls Autoreninformationen vertraulich sind oder nicht oeffentlich sein sollen, den Organisationsnamen anstelle persoenlicher Details verwenden oder den Abschnitt fuer interne Projekte weglassen.

Schritt 5: Sicherheitsrichtlinien hinzufuegen

## Sicherheit & Vertraulichkeit

- Niemals `.Renviron`, `.env` oder Dateien mit Token committen
- Platzhalterwerte in der Dokumentation verwenden: `YOUR_TOKEN_HERE`
- Umgebungsvariablen fuer alle Geheimnisse
- Per git ignoriert: `.Renviron`, `.env`, `credentials.json`

Erwartet: Der Sicherheitsabschnitt listet Dateien auf, die niemals committet werden duerfen, Platzhalterkonventionen fuer die Dokumentation und bestaetigt, dass 

.gitignore
alle sensiblen Dateien abdeckt.

Bei Fehler: Falls unklar ist, welche Dateien sensibel sind, 

grep -rn "sk-\|ghp_\|password" .
ausfuehren, um nach exponierten Geheimnissen zu suchen. Jede Datei mit echten Anmeldedaten sollte zu 
.gitignore
hinzugefuegt und in diesem Abschnitt erwaehnt werden.

Schritt 6: Skills und Anleitungen referenzieren

## Entwicklungs-Best-Practices-Referenzen
@agent-almanac/skills/write-testthat-tests/SKILL.md
@agent-almanac/skills/submit-to-cran/SKILL.md

Erwartet: Relevante Skills und Anleitungen werden ueber 

@
-Pfade referenziert, wodurch KI-Assistenten Zugang zu detaillierten Verfahren fuer haeufige Aufgaben im Projekt erhalten.

Bei Fehler: Falls die referenzierten Skills oder Anleitungen nicht an den angegebenen Pfaden existieren, Pfade pruefen oder Referenzen entfernen. Fehlerhafte 

@
-Referenzen bieten keinen Mehrwert und koennen den Assistenten verwirren.

Schritt 7: Qualitaets- und Statusinformationen hinzufuegen

## Qualitaetsstatus

- R CMD check: 0 Fehler, 0 Warnungen, 1 Hinweis
- Testabdeckung: 85 %
- Tests: 200+ bestanden
- Vignetten: 3 (bewertet mit 9/10)

Erwartet: Der Qualitaetsmetrik-Abschnitt spiegelt den aktuellen Stand des Projekts mit genauen Zahlen fuer Check-Ergebnisse, Testabdeckung, Testanzahl und Dokumentationsstatus wider.

Bei Fehler: Falls Metriken noch nicht verfuegbar sind (neues Projekt), Platzhaltereintraege mit "TBD" hinzufuegen und aktualisieren, wenn das Projekt reift. Keine Zahlen erfinden.

Validierung

  • CLAUDE.md befindet sich im Projektstammverzeichnis
  • Schnellstart-Befehle sind korrekt und funktionieren
  • Architekturabschnitt spiegelt die tatsaechliche Projektstruktur wider
  • Keine sensiblen Informationen (Token, Passwoerter, private Pfade)
  • MCP-Server-Konfigurationen sind aktuell
  • Referenzierte Dateien und Pfade existieren

Haeufige Stolperfallen

  • Veraltete Informationen: CLAUDE.md aktualisieren, wenn sich die Projektstruktur aendert
  • Zu viel Detail: Praegnant halten. Auf detaillierte Anleitungen verlinken anstatt Inhalte zu duplizieren.
  • Sensible Daten: Niemals echte Token oder Anmeldedaten einbeziehen. Platzhalter verwenden.
  • Widerspruechliche Anweisungen: Sicherstellen, dass CLAUDE.md anderen Konfigurationsdateien nicht widerspricht
  • Fehlt in 
    .Rbuildignore
    : Fuer R-Pakete 
    ^CLAUDE\\.md$
    zu 
    .Rbuildignore
    hinzufuegen

Beispiele

In erfolgreichen Projekten beobachtetes Muster:

  1. putior (829 Zeilen): Umfassende CLAUDE.md mit Qualitaetsmetriken, 20 Errungenschaften, MCP-Integrationsdetails und Entwicklungsworkflow
  2. Einfaches Projekt (20 Zeilen): Nur Schnellstart-Befehle und Schluesselbconventionen

Die CLAUDE.md entsprechend der Projektkomplexitaet skalieren.

Verwandte Skills

  • create-r-package
    - CLAUDE.md als Teil der Paketeinrichtung
  • configure-mcp-server
    - MCP-Konfiguration in CLAUDE.md referenziert
  • security-audit-codebase
    - pruefen ob keine Geheimnisse in CLAUDE.md