Collaboration Rules

How we work together on this project.

Honesty and Objectivity

Evaluate all suggestions on their technical merits. No sycophancy — if something doesn't make sense, doesn't align with best practices, or could be improved, say so directly and constructively. Technical accuracy and project quality take precedence over being agreeable.

Core Workflow: Research → Plan → Implement → Validate

Every non-trivial feature or bug fix follows this sequence:

Research — Read the relevant code. Understand existing patterns before touching anything.
Plan — Write a plan to /.agent/current-plan.md and align with the user before writing code. Update the plan as work progresses.
Implement — Build with tests and error handling. Use pure functions where possible.
Validate — Run formatters, linters, and tests after every implementation step.

Never start writing code without having read the relevant files first.

Issue Tracking (Gitea)

All work is tracked in Gitea at http://192.168.178.71:3005 (repo marcel/familienarchiv). Never use todo files or CLAUDE.md notes as a substitute.

Create an issue whenever work is identified that isn't being done in the current session.

Issue title formats

feature label — user story format:

As a [role] I want [capability] so/because [reason]

Examples:

"As a user I want to search documents so I can find a specific document faster"
"As an admin I want to add a new user so I don't have to restart the server"

bug label — user-facing impact, not the technical cause:

[What breaks] when [trigger]

Examples:

"Document list shows blank page when no results found"
"Upload fails silently when file exceeds 50MB"

devops label — infrastructure, CI/CD, deployment, tooling:

"Fix CI checkout failing due to unresolvable hostname"
"Add E2E test seed data for runner"

Priority labels

priority: high — blocking or urgent
priority: medium — normal
priority: low — nice to have

Other labels

needs-discussion — decision needed before work starts
wontfix — acknowledged, not addressing

Commit Messages

Every commit must reference the relevant Gitea issue.

Closes #12 — commit fully resolves the issue (Gitea auto-closes it)
Refs #12 — commit is related but doesn't fully close the issue

Place the reference at the end of the commit body:

feat: add person typeahead to document edit form

Closes #7
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Code Style Reminders

Pure functions over stateful helpers where possible
No premature abstractions — solve the problem in front of you
No backwards-compatibility shims for code that has no callers
Validate at system boundaries only (user input, external APIs)

2.8 KiB Raw Blame History