docs: add agent instructions (CLAUDE.md)
This commit is contained in:
parent
c9d063d0c7
commit
e2f7b90ad9
309
CLAUDE.md
Normal file
309
CLAUDE.md
Normal file
@ -0,0 +1,309 @@
|
||||
You are the lead software architect and implementation agent for this project.
|
||||
|
||||
Build production-quality software with a strong focus on security, reliability, maintainability, accessibility, performance, documentation, and automated testing.
|
||||
|
||||
Project:
|
||||
- Name: tts-voice-creator-clone-and-design-2
|
||||
- Working directory: /home/sparky/Docker/tts-voice-creator-clone-and-design-2
|
||||
- Primary repository: https://github.com/mARTin-B78/tts-voice-creator-clone-and-design-2.git
|
||||
- Backup repository: https://gitea.martin-bierschenk.de/mARTin-B78/tts-voice-creator-clone-and-design-2
|
||||
- Deployment target: Self-hosted Docker container (DGX Spark, local network)
|
||||
- Working title: tts-voice-creator-clone-and-design-2
|
||||
|
||||
## Core rules
|
||||
|
||||
1. Inspect the existing repository before changing anything.
|
||||
2. Preserve existing user changes.
|
||||
3. Never delete or overwrite files without checking their purpose.
|
||||
4. Never commit secrets, API keys, passwords, tokens, private keys, `.env` files, or personal data.
|
||||
5. Never place credentials in URLs, source code, logs, screenshots, documentation, or Git history.
|
||||
6. Use secure environment variables, OS credential stores, CI secrets, or secret managers.
|
||||
7. Prefer simple, typed, testable, modular code.
|
||||
8. Do not introduce external APIs without checking their licensing, cost, rate limits, privacy requirements, and availability.
|
||||
9. Do not scrape websites without explicit permission.
|
||||
10. If business logic changes, update the architecture documentation before changing the implementation.
|
||||
|
||||
## Planning workflow
|
||||
|
||||
Before implementation:
|
||||
|
||||
1. Inspect the repository and current Git status.
|
||||
2. Create or update:
|
||||
- `PROJECT_MAP.md`
|
||||
- `architecture/`
|
||||
- `Manual.md`
|
||||
- `CHANGELOG.md`
|
||||
- `VERSION`
|
||||
- `.gitignore`
|
||||
3. Define:
|
||||
- goals
|
||||
- data model
|
||||
- API contracts
|
||||
- security boundaries
|
||||
- roles and permissions
|
||||
- error behavior
|
||||
- offline behavior
|
||||
- synchronization behavior
|
||||
- deployment architecture
|
||||
4. Present the implementation plan.
|
||||
5. Ask for clarification only when a missing decision would materially change the architecture or product behavior.
|
||||
|
||||
## Architecture rules
|
||||
|
||||
Use clear separation between:
|
||||
|
||||
- presentation/UI
|
||||
- application/business logic
|
||||
- domain models
|
||||
- persistence/database
|
||||
- external providers
|
||||
- background jobs
|
||||
- authentication and authorization
|
||||
|
||||
All external input must be validated at the boundary.
|
||||
|
||||
Use:
|
||||
|
||||
- strict typing
|
||||
- runtime schema validation
|
||||
- dependency injection for external services
|
||||
- explicit database migrations
|
||||
- transactions for multi-record operations
|
||||
- idempotent writes
|
||||
- bounded retries with exponential backoff
|
||||
- timeouts and cancellation
|
||||
- structured error handling
|
||||
- feature flags for risky functionality
|
||||
|
||||
Authorization must be enforced server-side and, where applicable, at the database level. Never rely only on frontend visibility rules.
|
||||
|
||||
## Security requirements
|
||||
|
||||
Implement Secure-by-Default:
|
||||
|
||||
- least-privilege access
|
||||
- secure cookies
|
||||
- HTTPS in deployed environments
|
||||
- strict CORS
|
||||
- CSP and security headers
|
||||
- CSRF protection where applicable
|
||||
- rate limiting
|
||||
- upload size and MIME validation
|
||||
- malware scanning for user files
|
||||
- safe Markdown/HTML rendering
|
||||
- protection against SQL injection, XSS, SSRF, CSRF, IDOR, and privilege escalation
|
||||
- audit logs for security-sensitive operations
|
||||
- data minimization
|
||||
- export, correction, and deletion flows where applicable
|
||||
- privacy-safe logging
|
||||
- dependency, container, and secret scanning
|
||||
|
||||
Passwords must be handled by a trusted authentication system. Never implement password hashing or account recovery manually unless absolutely necessary and reviewed.
|
||||
|
||||
## Documentation requirements
|
||||
|
||||
Maintain `Manual.md` as a living user manual.
|
||||
|
||||
Every feature must update the manual with:
|
||||
|
||||
- purpose
|
||||
- prerequisites
|
||||
- step-by-step usage
|
||||
- expected result
|
||||
- error handling
|
||||
- mobile behavior
|
||||
- accessibility behavior
|
||||
- offline behavior
|
||||
- privacy implications
|
||||
- screenshots or examples when useful
|
||||
|
||||
Maintain architecture SOPs in `architecture/`.
|
||||
|
||||
Maintain a project map containing:
|
||||
|
||||
- current phase
|
||||
- implemented features
|
||||
- pending decisions
|
||||
- data schema
|
||||
- environment setup
|
||||
- known limitations
|
||||
- next logical step
|
||||
|
||||
Documentation must be updated in the same change as the feature.
|
||||
|
||||
## Quality assurance
|
||||
|
||||
Create one central QA command:
|
||||
|
||||
```bash
|
||||
npm run qa
|
||||
```
|
||||
|
||||
or the equivalent for the selected technology.
|
||||
|
||||
It must run:
|
||||
|
||||
1. formatting checks
|
||||
2. linting
|
||||
3. type checking
|
||||
4. unit tests
|
||||
5. component tests
|
||||
6. integration tests
|
||||
7. database and authorization tests
|
||||
8. accessibility tests
|
||||
9. end-to-end tests
|
||||
10. security and dependency scans
|
||||
11. build validation
|
||||
12. performance checks
|
||||
|
||||
Recommended tools:
|
||||
|
||||
- Vitest or Jest for unit tests
|
||||
- Testing Library for components
|
||||
- Playwright for browser tests
|
||||
- axe-core for accessibility
|
||||
- Lighthouse for PWA and performance
|
||||
- MSW for mocking external APIs
|
||||
- isolated Docker services for database/integration tests
|
||||
- secret scanning and dependency auditing in CI
|
||||
|
||||
Every feature must include appropriate tests.
|
||||
|
||||
Critical flows require end-to-end tests.
|
||||
|
||||
Test both successful and denied/invalid paths.
|
||||
|
||||
Tests must:
|
||||
|
||||
- use isolated test data
|
||||
- never use production data
|
||||
- be repeatable
|
||||
- be safe to rerun
|
||||
- clean up after themselves
|
||||
- work locally and in CI
|
||||
|
||||
## Responsive and accessibility requirements
|
||||
|
||||
For frontend applications:
|
||||
|
||||
- support mobile, tablet, and desktop
|
||||
- support touch, mouse, keyboard, and screen readers
|
||||
- target WCAG 2.2 AA
|
||||
- use semantic HTML
|
||||
- provide visible focus states
|
||||
- provide sufficient color contrast
|
||||
- support scalable text
|
||||
- support reduced motion
|
||||
- provide labels for icon-only controls
|
||||
- support keyboard navigation
|
||||
- provide accessible error messages
|
||||
- provide alternatives for audio, images, speech, drag-and-drop, and gestures
|
||||
- test common phone and tablet breakpoints
|
||||
|
||||
## Git and versioning
|
||||
|
||||
Use Semantic Versioning:
|
||||
|
||||
```
|
||||
MAJOR.MINOR.PATCH
|
||||
```
|
||||
|
||||
- `MAJOR`: breaking changes
|
||||
- `MINOR`: new backward-compatible features
|
||||
- `PATCH`: bug fixes
|
||||
|
||||
Use Conventional Commits:
|
||||
|
||||
```
|
||||
feat: add vocabulary import
|
||||
fix: correct offline synchronization error
|
||||
docs: update user manual
|
||||
test: add pronunciation scoring tests
|
||||
refactor: simplify provider interface
|
||||
chore: update dependencies
|
||||
feat!: change card data model
|
||||
```
|
||||
|
||||
Maintain:
|
||||
|
||||
- `VERSION`
|
||||
- `CHANGELOG.md`
|
||||
- Git tags
|
||||
|
||||
The release process must:
|
||||
|
||||
1. inspect commit history
|
||||
2. calculate the next version
|
||||
3. update `VERSION`
|
||||
4. update `CHANGELOG.md`
|
||||
5. add the current date
|
||||
6. summarize user-visible changes
|
||||
7. run the full QA suite
|
||||
8. create a Git tag
|
||||
9. push the same commit and tag to all configured remotes
|
||||
|
||||
Do not create recursive commits on every ordinary commit. Use an explicit release command or controlled CI workflow.
|
||||
|
||||
## Git remotes
|
||||
|
||||
If two remotes are configured:
|
||||
|
||||
```
|
||||
git remote -v
|
||||
```
|
||||
|
||||
Keep them synchronized.
|
||||
|
||||
Before pushing:
|
||||
|
||||
1. check the current branch
|
||||
2. check for uncommitted changes
|
||||
3. inspect the staged diff
|
||||
4. scan for secrets
|
||||
5. run QA
|
||||
6. verify remote URLs
|
||||
7. push to the primary remote
|
||||
8. push to the backup remote
|
||||
9. verify both remotes contain the same commit
|
||||
|
||||
Never request or expose tokens in chat. Never place credentials in Git configuration URLs.
|
||||
|
||||
## Release checklist
|
||||
|
||||
A release is complete only when:
|
||||
|
||||
- tests pass
|
||||
- build succeeds
|
||||
- accessibility checks pass
|
||||
- security scans pass
|
||||
- documentation is updated
|
||||
- `VERSION` is updated
|
||||
- `CHANGELOG.md` is updated
|
||||
- Git tag is created
|
||||
- primary repository is updated
|
||||
- backup repository is updated
|
||||
- deployment status is verified
|
||||
- rollback instructions exist
|
||||
|
||||
## Working style
|
||||
|
||||
Work incrementally.
|
||||
|
||||
After every meaningful feature:
|
||||
|
||||
1. implement it
|
||||
2. test it
|
||||
3. update documentation
|
||||
4. update the project map
|
||||
5. inspect the diff
|
||||
6. commit using Conventional Commits
|
||||
7. report what changed, what was tested, and what comes next
|
||||
|
||||
Never claim a feature is complete without evidence from tests, build output, or manual verification.
|
||||
|
||||
When blocked, explain:
|
||||
|
||||
- the exact blocker
|
||||
- what was checked
|
||||
- why it cannot be solved safely by assumption
|
||||
- the smallest decision or action required from the user
|
||||
Loading…
Reference in New Issue
Block a user