# Portabilität: UNIVERSAL
# Version: 1.0.1
# Zuletzt validiert: 2026-02-08
# Nächste Prüfung: 2026-08-08

BEST PRACTICES
==============

BACH CLI ERSTE WAHL:
  Für alle Operationen IMMER bach.py nutzen
  - Tasks           --> bach task add/list/done
  - Memory          --> bach mem write/read
  - Skills          --> bach --skills list/search
  - Tools           --> bach tools list/run

WARUM?
  - Encoding-sicher (UTF-8)
  - Validiert Struktur
  - Keine Korruption
  - Atomare Operationen
  - Einheitliche Schnittstelle

ALTERNATIVEN (NUR WENN CLI NICHT GEHT):
  1. Python-Script mit bach_paths.py
  2. Direkte DB-Abfrage (nur lesen!)
  3. Niemals manuelle JSON-Bearbeitung!

REGELWERK-INDEX:
  Was?                      Wo?
  CLI-Syntax                --help cli
  Memory-Regeln             --help memory
  Task-System               --help tasks
  Coding-Standards          --help coding
  Ordnerstruktur            --help bach_paths
  Namenskonventionen        --help naming
  Datenformate              --help formats
  Bekannte Probleme         --help lessons
  Tool-Übersicht           --help tools
  Tool-Praefixe             --help naming (Abschnitt TOOL-PRAEFIXE)
  Policy-Validatoren        tools/_policies/

ARCHITEKTUR-PRINZIPIEN:
-----------------------
Diese Regeln gelten systemweit:

1. KONZEPTE ZENTRAL IN DOCS/ ABLEGEN
   Alle CONCEPT_*.md gehören nach docs/ (Root-Verzeichnis).
   EIN Ort für alle Plaene = bessere Übersicht.

   Nach Umsetzung: Konzept nach docs/_archive verschieben.

   MARKDOWN-DATEIEN IM SYSTEM:
   - docs/CONCEPT_*.md  = Konzepte und Plaene (zentral!)
   - */README.md        = Ordner-Wegweiser, Index
   - skills/SKILL.md    = Agent/Skill-Dokumentation
   - skills/*.md        = Agent-Hauptdokument (ATI.md, STEUER.md)

   REGEL: Dezentrale .md sind NUR für Navigation und Skill-Doku,
          NICHT für Konzepte oder Plaene.

2. DOCS/ ORDNERSTRUKTUR
   docs/ betrifft die ENTWICKLUNG des Systems:

   _archive/          Archivierte Altkonzepte (umgesetzt/obsolet)
   _ideas/            Langfristige Konzepte (noch nicht approved)
   _test_and_reports/ Entwickler-Analysen, Jetztstände, Tests
   analyse/           Analyse-Ergebnisse und Berichte
   reference/         Referenz-Dokumentation
   (root)             CONCEPT_*.md - Alle Konzepte zentral
                      EIN Ort für alle Plaene zur Umsetzung

   user/ betrifft die NUTZUNG des Systems:
   - Reports die durch Nutzung entstehen
   - Nicht für System-Entwicklung

3. EVOLUTIONAERE MIGRATION
   Keine harten Brueche bei Umbenennungen/Umstrukturierungen.
   Alte Strukturen schrittweise migrieren, nicht auf einmal.

4. EINE UNIFIED DATENBANK
   bach.db      = Einzige Haupt-DB (210+ Tabellen, alles drin)

   Hinweis: user.db wurde in v1.1.84 in bach.db zusammengeführt.
   registry.db (Distribution) und archive.db (Archiv) sind
   Spezial-DBs, nicht Teil des Kern-Systems.

5. DATENBANK VOR JSON (RecludOS-Lehre!)
   JSON-Dateien nur in begründeten Ausnahmefaellen.
   Standard ist IMMER die Datenbank.

   JSON erlaubt nur wenn:
   - Nutzer-spezifisch (frisch erstellt, nicht migriert)
   - Transparenz wichtig (Nutzer soll direkt editieren)
   - Prozess-Charakter (kurzlebig, Verarbeitung)
   - Import/Export Austauschformat

   Details: docs/help/formats.txt

6. DIST_TYPE DREISCHRITT
   2 = CORE (Systemdatei, Distribution ist Backup)
   1 = TEMPLATE (1x Snapshot für Reset)
   0 = USER (Userdaten, normale Rotation)

7. HELP ALS WAHRHEIT
   docs/help/*.txt ist die primaere Dokumentation.
   Bei Widerspruch: docs/help/ gewinnt.
