Conrad Schulz
045e2e7202
- New repo convention: /data/<service>/ for all persistent service data (gitignored) - New repo convention: /history/prompts/ (gitignored) + /history/summary/PROJECT_CONTEXT.md for agent session logging and compressed project context - git-templates/hooks/pre-commit: quality gate checking tests + docs on every commit - git-templates/docs/: USER.md, ADMIN.md, MAINTAINER.md templates (3 target groups) - git-templates/history/summary/PROJECT_CONTEXT.md: agent context template - prompts/history.prompt.md: /history prompt for logging sessions + updating summary - copilot-bootstrap.sh: creates all new folders, .gitignore entries, installs hook - deploy.sh + deploy.fish: deploy hooks, doc templates, history template - docs/ADMIN.md: new admin handbook for this project - docs/USER.md + docs/MAINTAINER.md: updated with new conventions - git-templates/.github/copilot-instructions.md: extended DoD + new conventions - README.md: updated structure overview + prompt table
106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# GitHub Copilot – Project Instructions
|
||
|
||
## Project
|
||
<!-- TODO: Beschreibe das Projekt in 1-2 Sätzen -->
|
||
|
||
## Stack
|
||
<!-- TODO: Sprachen, Frameworks, wichtige Tools -->
|
||
- Language:
|
||
- Framework:
|
||
- Database:
|
||
- Infrastructure:
|
||
|
||
## Architecture
|
||
<!-- TODO: Relevante Architekturentscheidungen -->
|
||
- Pattern (MVC / Hexagonal / Event-driven / ...):
|
||
- Key constraints:
|
||
- ADR location: `docs/adr/`
|
||
|
||
## Project Structure Conventions
|
||
|
||
### Persistent Data (`/data/`)
|
||
- **Alle persistenten Service-Daten** gehören in `/data/<service-name>/` (Repo-Root)
|
||
- **Nie** Daten-Dateien committen – `/data/` ist vollständig gitignored
|
||
- Einen Unterordner pro Service (z.B. `data/postgres/`, `data/redis/`, `data/uploads/`)
|
||
- Erforderliche Unterordner in `docs/ADMIN.md` dokumentieren
|
||
|
||
### Agent History (`/history/`)
|
||
- **Vollständige Konversationen** → `history/prompts/YYYY-MM-DD_beschreibung.md` (gitignored)
|
||
- **Komprimierter Kontext** → `history/summary/PROJECT_CONTEXT.md` (**committed, immer aktuell halten!**)
|
||
- **Beim Start einer neuen Session:** `history/summary/PROJECT_CONTEXT.md` zuerst lesen
|
||
- **Am Ende jeder Session:** `PROJECT_CONTEXT.md` aktualisieren und committen
|
||
- Copilot Chat: `/history` → History loggen + Summary aktualisieren
|
||
|
||
### Documentation (3 Zielgruppen – alle 3 müssen existieren)
|
||
| Datei | Zielgruppe | Inhalt |
|
||
|---|---|---|
|
||
| `docs/USER.md` | Endnutzer | Features, How-To, FAQ – keine technischen Details |
|
||
| `docs/ADMIN.md` | Administratoren | Deployment, Konfiguration, Monitoring, Backup |
|
||
| `docs/MAINTAINER.md` | Entwickler | Architektur, ADRs, Konventionen, Erweiterung |
|
||
|
||
**Regel:** Jede bedeutende Änderung muss mindestens eine dieser Dateien aktualisieren.
|
||
Der pre-commit Hook prüft dies automatisch.
|
||
|
||
## Conventions
|
||
<!-- TODO: Projekt-spezifische Konventionen -->
|
||
- Branch naming: `feat/<ticket>-description`, `fix/<ticket>-description`
|
||
- Commit format: Conventional Commits (`feat|fix|chore|docs|refactor|test|ci`)
|
||
- File structure:
|
||
- Naming:
|
||
|
||
## Engineering Process
|
||
|
||
### Before starting any task
|
||
1. Clarify requirements – user story + acceptance criteria vorhanden?
|
||
2. Impact analysis – welche bestehenden Komponenten sind betroffen?
|
||
3. Architecture check – passt die geplante Lösung zur bestehenden Architektur?
|
||
4. Test strategy – wie wird das Feature getestet?
|
||
|
||
### Definition of Ready (DoR)
|
||
A task can only be started when:
|
||
- [ ] Acceptance criteria are clear and unambiguous
|
||
- [ ] Non-functional requirements defined (performance, security, scalability)
|
||
- [ ] Architectural approach agreed upon
|
||
- [ ] No unresolved external blockers
|
||
|
||
### Definition of Done (DoD)
|
||
A task is only done when ALL of the following are true:
|
||
- [ ] Code implements the acceptance criteria
|
||
- [ ] Unit tests written and passing
|
||
- [ ] Integration tests (where applicable) passing
|
||
- [ ] No linter / type errors
|
||
- [ ] No secrets or credentials in code
|
||
- [ ] OWASP Top 10 reviewed
|
||
- [ ] Relevant documentation updated: `docs/USER.md` and/or `docs/ADMIN.md` and/or `docs/MAINTAINER.md`
|
||
- [ ] Alle 3 Zielgruppen-Dokumente vorhanden (`docs/USER.md`, `docs/ADMIN.md`, `docs/MAINTAINER.md`)
|
||
- [ ] Persistente Daten liegen ausschließlich in `/data/<service>/` (nie woanders)
|
||
- [ ] `history/summary/PROJECT_CONTEXT.md` aktualisiert
|
||
- [ ] Commit message follows Conventional Commits
|
||
- [ ] No dead code, no TODOs left behind (or tracked as issues)
|
||
- [ ] pre-commit Quality Gate bestanden (oder Bypass bewusst begründet)
|
||
|
||
## Testing Strategy
|
||
<!-- TODO: Anpassen auf das Projekt -->
|
||
- Framework:
|
||
- Coverage target: ≥ 80% (critical paths: 100%)
|
||
- Test pyramid: unit > integration > e2e
|
||
- Test location: `tests/` mirroring source structure
|
||
|
||
## Security
|
||
- No secrets in code or config files – use environment variables
|
||
- Validate all inputs at system boundaries
|
||
- Principle of least privilege for all permissions
|
||
- Dependency vulnerabilities: check before adding new deps
|
||
|
||
## Documentation Standards
|
||
- Code comments: explain WHY, not WHAT
|
||
- Public APIs: always documented
|
||
- Architecture decisions: write ADR in `docs/adr/` (template: `docs/adr/000-template.md`)
|
||
- CHANGELOG.md: update with every release
|
||
- **3-Zielgruppen-Regel:** USER.md (Endnutzer) + ADMIN.md (Ops) + MAINTAINER.md (Dev) – immer alle 3 pflegen
|
||
|
||
## Non-Functional Requirements
|
||
<!-- TODO: Anpassen -->
|
||
- Response time:
|
||
- Availability:
|
||
- Data retention:
|