ki-praxis/templates/agents-md-monorepo-package.md

AGENTS.md (Package — Beispiel)

Beispiel für packages/billing/AGENTS.md (Pfad anpassen).
Ergänzt die Root-AGENTS.md, ersetzt sie nicht. Bei Konflikt: spezifischere Package-Regel + Konflikt melden.

# Agent instructions — packages/billing

## Zweck
Billing-Domain: Rechnungen, Zahlungsmethoden, Webhooks der Payment-Provider.
Kein generisches Utility-Package.

## Ownership
- Team: <payments>
- Codeowners: `@your-org/payments`

## Scope (Schreiben)
**Erlaubt ohne Rückfrage (im Task-Scope):**
- `packages/billing/**`
- Tests unter `packages/billing/**`

**Nur mit explizitem Auftrag:**
- `packages/shared-types/**` (Contract-Änderungen)
- `apps/**` (UI/BFF-Verbraucher)
- Root-Configs, Lockfiles, CI

**Verboten ohne Auftrag:**
- Refactors außerhalb Billing
- neue Top-Level-Packages
- Provider-Credentials oder Live-API-Calls gegen Prod

**Permissions:** Root- und Harness-Allow/Deny gelten. Dieses File ist die Write-Allowlist, kein zweites Permission-System.

## Imports / Boundaries
- Darf: `packages/core`, `packages/shared-types` (öffentliche API)
- Darf nicht: `apps/*`, andere Domain-Packages außer freigegebenen Contracts
- Public API dieses Packages: `packages/billing/src/index.ts` (kein Deep-Import von außen)

## Conventions
- Fehler: Result/Domain-Error-Pattern wie in `src/errors.ts`
- Geld: Integer Minor Units, keine `number`-Floats für Currency
- Webhooks: Idempotenz-Keys, bestehende Middleware nutzen
- Logging: strukturiert, keine PAN/PII in Logs

## Definition of Done (dieses Package)
- `pnpm turbo run lint test --filter=@your-org/billing`
- oder: `pnpm nx run billing:lint` und `pnpm nx run billing:test`

Bei Contract-Änderungen an `shared-types` zusätzlich:
- Downstream-Consumer suchen und anpassen **oder** Task stoppen und Handoff schreiben, wenn außerhalb Scope.
- Generierten Client nur über den dokumentierten Codegen-Befehl aktualisieren.

## Explore-Hinweise
- Einstieg: `src/index.ts`, `src/invoices/`, `README.md` in diesem Ordner
- Payment-Provider-Adapter: `src/providers/`
- Nicht: `dist/`, Coverage, alte `*.bak`-Experimente

## Parallelität
- Nicht parallel mit einem zweiten Agent an `packages/billing` arbeiten.
- Parallel ok mit Agents in unzusammenhängenden Packages (ohne shared Contract-Touch).

Pflege

• Wenn die Public API wandert, diese Datei und Root-Filter am selben Tag aktualisieren.
• Widersprüche zur Root-AGENTS.md aktiv melden und auflösen.