david_bai
151 lines
7.1 KiB
Markdown
151 lines
7.1 KiB
Markdown
# PrivyDrop AI Playbook — Collaboration Rules
|
||
|
||
These rules govern how “human developers + AI assistants” collaborate to evolve the codebase efficiently and safely, without breaking the privacy stance or technical baseline. This document complements the index (`index.md`) and the flow map (`flows.md`): it constrains “how we work” without re-stating “what the system does”.
|
||
|
||
- Scope: the entire repository (code + docs)
|
||
- Audience: human developers, AI assistants, reviewers
|
||
- Change principles: best practices first, one goal per change, reversible, verifiable
|
||
|
||
## 1. Collaboration Principles
|
||
|
||
- Best practices first: prefer proven approaches consistent with the existing stack; avoid reinventing the wheel.
|
||
- One change, one purpose: each change should focus on one goal; avoid “while I’m here” fixes.
|
||
- Privacy stance: never introduce (or suggest) server-relayed file transfers; the backend is for signaling and room coordination only.
|
||
- Small steps: keep PRs small and easy to roll back; prefer the minimum viable change.
|
||
- Traceability: commit messages, PR descriptions, and code comments should be clear and reproducible.
|
||
|
||
## 2. Plan First (Hard Requirement)
|
||
|
||
Before implementing anything, you must propose a “change plan” and get approval. The plan must include: goals, scope + file list, approach, risks + mitigations, acceptance criteria, rollback, docs to update, and validation.
|
||
|
||
Recommended reading before implementation (and reference in the plan):
|
||
|
||
- `docs/ai-playbook/index.md`
|
||
- `docs/ai-playbook/code-map.md`
|
||
- `docs/ai-playbook/flows.md`
|
||
|
||
## 3. Language & Comments
|
||
|
||
- Communication: always use Simplified Chinese when communicating with the project owner/maintainers.
|
||
- Code comments, exported symbol naming, commit messages, and PR titles/descriptions must be in English.
|
||
- User/marketing docs may be bilingual; this collaboration guide is maintained in both languages.
|
||
- Use TSDoc/JSDoc (English) for exported functions, complex flows, and shared types to keep APIs readable.
|
||
|
||
## 4. Next.js (Frontend) Conventions
|
||
|
||
- App Router defaults to Server Components; use `"use client"` only when interaction truly requires it.
|
||
- Reuse existing UI (Tailwind + shadcn/ui + Radix); do not introduce new UI libraries without approval.
|
||
- i18n: all visible copy must go through dictionaries and the `frontend/app/[lang]` routes; do not hardcode strings in components.
|
||
- Naming & files:
|
||
- Components: PascalCase file names and exports (ExampleCard.tsx)
|
||
- Hooks: camelCase file names; exports start with use* (useSomething.ts)
|
||
- Centralize types/constants; avoid circular deps
|
||
- SEO: use Next Metadata and `frontend/components/seo/JsonLd.tsx`; pages must include canonical and multilingual links.
|
||
- Performance & a11y: dynamically import heavy components when needed; ensure basic aria/focus behavior.
|
||
|
||
## 5. TypeScript & Style
|
||
|
||
- Keep types strict; avoid any. Use unknown when needed and narrow explicitly; exported functions should have explicit return types.
|
||
- Follow existing ESLint/Prettier and path aliases (`@/...`); do not introduce new formatters.
|
||
- Keep functions small and clear; move complex logic into service/util layers. Components should consume state, not mutate global state.
|
||
- Avoid 1-letter variable names; avoid magic numbers—centralize them as constants.
|
||
|
||
## 6. WebRTC / Transfer Guardrails (Do Not Break)
|
||
|
||
- Keep established strategy: 32MB batches + 64KB network chunks; do not casually change DataChannel bufferedAmountLowThreshold or maxBuffer strategy.
|
||
- Resume, strict sequential disk writes, and multi-format compatibility are baseline capabilities—do not downgrade/remove them.
|
||
- Signaling and message names (offer/answer/ice-candidate, etc.) must stay compatible; any breaking change must follow the “must ask” process.
|
||
- Reconnect and queue handling (ICE candidate caching, backpressure, send retries) must remain consistent; changes require risk assessment and thorough validation.
|
||
- Never send file contents (in any form) to the backend or third-party services.
|
||
|
||
## 7. Backend Constraints (Signaling Service)
|
||
|
||
- Signaling + room management only. Never persist user file data; logs must not include sensitive content or raw payloads.
|
||
- Keep rate limiting and abuse protection; if extending APIs, ensure backward compatibility or provide a migration path.
|
||
|
||
## 8. Dependencies & Security
|
||
|
||
- New dependencies require justification in the plan: size (ESM/SSR compatibility), maintenance health, license, alternatives, security impact.
|
||
- Do not add telemetry/tracking; do not log sensitive data; follow least privilege.
|
||
- Inject config via env vars; never hardcode secrets or service endpoints in the repo.
|
||
|
||
## 9. Documentation Sync
|
||
|
||
- If code changes affect flows, interfaces, or key entry points, update in the same PR:
|
||
- `docs/ai-playbook/flows.zh-CN.md`
|
||
- `docs/ai-playbook/code-map.zh-CN.md`
|
||
- PRs must list “docs impacted” to avoid the playbook going stale; keep the index page lean and only update it when adding new links.
|
||
|
||
## 10. Validation & Regression
|
||
|
||
- Frontend: must build (`next build`); include manual verification for key paths (at least: create/join room, single/multi file, folder, large files, resume, cross-browser transfers, i18n routes + SEO metadata).
|
||
- Backend: Socket.IO core flow works.
|
||
- Regression checklist: reconnect flow, download counts + state cleanup, store single-source-of-truth constraint, browser compatibility (Chromium/Firefox).
|
||
|
||
## 11. Must Ask First (Approval Required)
|
||
|
||
- Breaking changes to protocols/message names/public APIs/storage formats.
|
||
- Architecture changes impacting privacy stance or crossing boundaries (any relay or persistence).
|
||
- New dependencies, new infrastructure, or large refactors.
|
||
- Changes to transfer guardrail parameters (chunking, backpressure, retries, etc.).
|
||
|
||
## 12. Common Pitfalls
|
||
|
||
- Mutating global state from inside components (breaks one-way dataflow).
|
||
- Changing code without updating docs, leaving the playbook stale.
|
||
- Using any to bypass type and boundary checks.
|
||
- Hardcoding UI copy in components instead of using dictionaries/i18n.
|
||
- Tweaking critical WebRTC parameters without validation, causing silent regressions.
|
||
|
||
## 13. Templates
|
||
|
||
Change Plan Template
|
||
|
||
```
|
||
Title: <concise title>
|
||
|
||
Goals
|
||
- <what you intend to achieve>
|
||
|
||
Scope / Files
|
||
- <files to change/add + why>
|
||
|
||
Approach
|
||
- <implementation approach and key design points>
|
||
|
||
Risks & Mitigations
|
||
- <major risk> -> <mitigation>
|
||
|
||
Acceptance Criteria
|
||
- <verifiable acceptance items>
|
||
|
||
Rollback
|
||
- <how to roll back quickly>
|
||
|
||
Docs to Update
|
||
- code-map.zh-CN.md / flows.zh-CN.md / README(.zh-CN).md / others?
|
||
|
||
Validation
|
||
- Build: next build / backend health
|
||
- Manual: <key scenarios>
|
||
```
|
||
|
||
PR Checklist
|
||
|
||
```
|
||
- [ ] Single-topic change only
|
||
- [ ] Code comments and commit messages are in English
|
||
- [ ] No unapproved dependencies/UI libraries added
|
||
- [ ] i18n and SEO follow conventions (if applicable)
|
||
- [ ] Transfer guardrails are unchanged (or approved + validated)
|
||
- [ ] flows / code-map docs are updated in sync
|
||
- [ ] Validation notes and regression checklist included
|
||
```
|
||
|
||
## 14. References & Quick Entry Points
|
||
|
||
- Index & context: `docs/ai-playbook/index.md`
|
||
- Code map: `docs/ai-playbook/code-map.md`
|
||
- Key flows: `docs/ai-playbook/flows.md`
|
||
|