@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/_shared/CLAUDE.md

@@ -1,174 +1,77 @@
 # Shared Conventions
 
-## Git Workflow
-
-### Branch Naming
-
-```
-feature/[ticket-id]-short-description
-fix/[ticket-id]-short-description
-refactor/description
-chore/description
-```
+## Code Quality
 
-### Commit Messages (Conventional Commits)
+### Naming - Be Explicit
 
-```
-type(scope): description
+- No cryptic names: No `c`, `x`, `tmp`, `data`
+- No magic numbers: Use named constants
+- Small functions: < 30 lines, single responsibility
+- Max nesting: 3 levels, use early returns
+- No dead code: Delete, don't comment out
 
-[optional body]
+### Lint Disable - Only With Justification
 
-[optional footer]
-```
+Never disable lint rules without an explicit reason and ticket reference.
 
-Types:
-- `feat`: New feature
-- `fix`: Bug fix
-- `docs`: Documentation only
-- `style`: Formatting, no code change
-- `refactor`: Code change that neither fixes a bug nor adds a feature
-- `perf`: Performance improvement
-- `test`: Adding or updating tests
-- `chore`: Maintenance tasks
+## Error Handling
 
-Examples:
-```
-feat(users): add user profile page
-fix(auth): resolve token refresh race condition
-refactor(api): simplify error handling
-test(cart): add unit tests for checkout flow
-```
+- Never swallow errors silently
+- Log with context (user ID, request ID)
+- User-facing: clear, actionable messages
+- Internal: detailed logs, generic user message
 
-### Pull Requests
+## Testing
 
-- Keep PRs small and focused
-- One feature/fix per PR
-- Write meaningful descriptions
-- Link related issues
-
-## TypeScript Guidelines
-
-### Strict Mode
-
-Always use strict TypeScript configuration:
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "noImplicitReturns": true
-  }
-}
-```
-
-### Type Definitions
-
-```typescript
-// Prefer interfaces for object shapes
-interface User {
-  id: string;
-  name: string;
-  email: string;
-}
-
-// Use type for unions, intersections, utility types
-type Status = 'pending' | 'active' | 'inactive';
-type UserWithRole = User & { role: Role };
-
-// Avoid 'any' - use 'unknown' if type is truly unknown
-function parse(input: unknown): Result {
-  // ...
-}
-```
-
-### Naming Conventions
-
-| Element | Convention | Example |
-|---------|------------|---------|
-| Classes | PascalCase | `UserService` |
-| Interfaces | PascalCase | `UserProfile` |
-| Functions | camelCase | `getUserById` |
-| Variables | camelCase | `currentUser` |
-| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
-| Files | kebab-case | `user-profile.service.ts` |
-| Folders | kebab-case | `user-management/` |
-
-### Explicit Return Types
-
-Always declare return types on public methods:
-
-```typescript
-// Good
-function getUser(id: string): User | null {
-  // ...
-}
-
-// Avoid
-function getUser(id: string) {
-  // ...
-}
-```
+- Test behavior, not implementation
+- Descriptive names: `should_returnUser_when_validId`
+- One assertion per test when practical
+- Mock external dependencies only
 
-## Code Quality
+## Security
 
-### Avoid
+- **Never commit secrets** (use env vars)
+- **Validate all inputs** (never trust user data)
+- **Parameterized queries** (no string concatenation)
+- **Sanitize outputs** (prevent XSS)
 
-- `any` type
-- Magic numbers (use named constants)
-- Deep nesting (max 3 levels)
-- Long functions (max ~50 lines)
-- Commented-out code
-- Useless comments (code should be self-documenting)
-- Cryptic variable names (`c`, `x`, `tmp`, `data`)
+## Documentation
 
-### Prefer
+- Self-documenting code first
+- Comments explain "why", not "what"
+- Keep comments up-to-date or delete them
 
-- Early returns
-- Descriptive variable names
-- Single responsibility principle
-- Composition over inheritance
-- Immutable data patterns
+## Git Workflow
 
-### Naming - Be Explicit
+### Commits
 
-```typescript
-// BAD
-const c = getConfig();
-users.filter(u => u.a);
-const handleClick = (e) => { ... };
+- Atomic commits: one logical change per commit
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`
+- Present tense: "add feature" not "added feature"
 
-// GOOD
-const appConfig = getConfig();
-users.filter(user => user.isActive);
-const handleUserSelection = (event: MouseEvent) => { ... };
-```
+### Branches
 
-### Lint Rules - Never Disable Without Justification
+- `feature/<ticket>-<description>` for new features
+- `fix/<ticket>-<description>` for bug fixes
+- `refactor/<description>` for refactoring
 
-```typescript
-// FORBIDDEN
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const data: any = response;
+### Pull Requests
 
-// ONLY IF ABSOLUTELY NECESSARY - with explicit reason
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Legacy API returns untyped, see ticket TECH-456
-const legacyData: any = legacyApi.fetch();
-```
+- Small, focused PRs (< 400 lines)
+- Clear description with context
+- Link to related issues
 
-## Documentation
+## Dependencies
 
-- Write self-documenting code first
-- Add JSDoc only when intent isn't obvious
-- Keep comments up-to-date or remove them
-- Document "why", not "what"
+- Pin exact versions in lock files
+- Regular security audits (`npm audit`, `pip-audit`)
+- Prefer well-maintained packages with active communities
+- Minimize dependency count
 
-```typescript
-// Bad: describes what code does
-// Increment counter by 1
-counter++;
+## Performance
 
-// Good: explains why
-// Compensate for 0-based index in display
-counter++;
-```
+- Measure before optimizing
+- Profile to find bottlenecks
+- Cache expensive operations
+- Lazy load when possible
+- Avoid premature optimization

package/configs/_shared/rules/conventions/documentation.md

@@ -0,0 +1,324 @@
+---
+paths:
+  - "**/README.md"
+  - "**/CHANGELOG.md"
+  - "**/docs/**"
+  - "**/ADR/**"
+---
+
+# Documentation Standards
+
+## README Structure
+
+```markdown
+# Project Name
+
+Brief description (1-2 sentences).
+
+## Quick Start
+
+\`\`\`bash
+# Clone and setup
+git clone <repo>
+cd project
+npm install
+npm run dev
+\`\`\`
+
+## Prerequisites
+
+- Node.js 20+
+- Docker
+- PostgreSQL 16
+
+## Installation
+
+Step-by-step setup instructions.
+
+## Usage
+
+Basic usage examples.
+
+## API Reference
+
+Link to API docs or brief overview.
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Server port | `3000` |
+| `DATABASE_URL` | DB connection | required |
+
+## Development
+
+\`\`\`bash
+npm run dev      # Start dev server
+npm run test     # Run tests
+npm run lint     # Lint code
+npm run build    # Build for production
+\`\`\`
+
+## Deployment
+
+How to deploy to production.
+
+## Contributing
+
+Link to CONTRIBUTING.md or brief guidelines.
+
+## License
+
+MIT / Apache-2.0 / etc.
+```
+
+## Architecture Decision Records (ADR)
+
+### Template
+
+```markdown
+# ADR-001: Use PostgreSQL as primary database
+
+## Status
+
+Accepted | Proposed | Deprecated | Superseded by ADR-XXX
+
+## Date
+
+2024-01-15
+
+## Context
+
+What is the issue we're facing? What are the constraints?
+
+## Decision
+
+What is the change we're making?
+
+## Consequences
+
+### Positive
+- Benefit 1
+- Benefit 2
+
+### Negative
+- Drawback 1
+- Drawback 2
+
+### Risks
+- Risk 1 and mitigation
+
+## Alternatives Considered
+
+1. **Alternative A**: Why rejected
+2. **Alternative B**: Why rejected
+```
+
+### Naming Convention
+
+```
+docs/adr/
+├── 001-use-postgresql.md
+├── 002-adopt-microservices.md
+├── 003-authentication-strategy.md
+└── README.md  # Index of all ADRs
+```
+
+## Changelog
+
+### Format (Keep a Changelog)
+
+```markdown
+# Changelog
+
+All notable changes to this project.
+
+## [Unreleased]
+
+### Added
+- New feature X
+
+### Changed
+- Updated dependency Y
+
+## [1.2.0] - 2024-01-15
+
+### Added
+- User authentication (#123)
+- Email notifications (#124)
+
+### Fixed
+- Login redirect issue (#125)
+
+### Security
+- Patched XSS vulnerability (#126)
+
+## [1.1.0] - 2024-01-01
+
+### Added
+- Initial release
+```
+
+### Categories
+
+- **Added**: New features
+- **Changed**: Changes in existing functionality
+- **Deprecated**: Soon-to-be removed features
+- **Removed**: Removed features
+- **Fixed**: Bug fixes
+- **Security**: Vulnerability fixes
+
+## API Documentation
+
+### OpenAPI/Swagger
+
+```yaml
+openapi: 3.0.3
+info:
+  title: My API
+  version: 1.0.0
+  description: API description
+
+paths:
+  /users:
+    get:
+      summary: List users
+      description: Returns paginated list of users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserList'
+```
+
+### Inline Documentation
+
+```typescript
+/**
+ * Creates a new user account.
+ *
+ * @param data - User registration data
+ * @returns Created user object
+ * @throws {ValidationError} When email is invalid
+ * @throws {ConflictError} When email already exists
+ *
+ * @example
+ * const user = await createUser({
+ *   email: 'user@example.com',
+ *   password: 'secure123'
+ * });
+ */
+async function createUser(data: CreateUserDto): Promise<User> {
+  // Implementation
+}
+```
+
+## Code Comments
+
+### When to Comment
+
+```typescript
+// GOOD: Explains WHY, not WHAT
+// Using retry with exponential backoff because the external API
+// has rate limiting and occasional timeouts
+await retryWithBackoff(() => externalApi.call());
+
+// BAD: Explains WHAT (obvious from code)
+// Loop through users
+for (const user of users) { ... }
+
+// GOOD: Documents non-obvious behavior
+// Note: Returns null instead of throwing when user not found
+// to support optional user lookups in middleware
+async function findUser(id: string): Promise<User | null>
+
+// GOOD: TODO with context
+// TODO(#123): Replace with proper caching once Redis is available
+const cache = new Map();
+```
+
+### Comment Types
+
+```typescript
+// TODO: Feature to implement
+// FIXME: Known bug to fix
+// HACK: Temporary workaround
+// NOTE: Important information
+// WARN: Potential issue
+// DEPRECATED: Will be removed
+```
+
+## Project Structure Documentation
+
+```markdown
+# Project Structure
+
+\`\`\`
+src/
+├── modules/           # Feature modules
+│   ├── users/         # User management
+│   │   ├── dto/       # Data transfer objects
+│   │   ├── entities/  # Database entities
+│   │   └── users.service.ts
+│   └── orders/        # Order management
+├── common/            # Shared utilities
+│   ├── decorators/    # Custom decorators
+│   ├── filters/       # Exception filters
+│   └── guards/        # Auth guards
+├── config/            # Configuration
+└── main.ts            # Entry point
+\`\`\`
+```
+
+## Runbooks
+
+### Template
+
+```markdown
+# Runbook: Database Connection Issues
+
+## Symptoms
+- API returning 500 errors
+- Logs show "Connection refused"
+
+## Diagnosis
+1. Check database status: `docker ps | grep postgres`
+2. Check connections: `SELECT count(*) FROM pg_stat_activity;`
+3. Check logs: `docker logs postgres`
+
+## Resolution
+
+### If database is down
+\`\`\`bash
+docker-compose restart db
+\`\`\`
+
+### If too many connections
+\`\`\`bash
+# Kill idle connections
+SELECT pg_terminate_backend(pid)
+FROM pg_stat_activity
+WHERE state = 'idle' AND query_start < now() - interval '1 hour';
+\`\`\`
+
+## Escalation
+Contact: @database-team in #incidents
+```
+
+## Anti-patterns
+
+- No README
+- Outdated documentation
+- Documenting WHAT instead of WHY
+- No ADRs for major decisions
+- Missing changelog
+- Undocumented environment variables
+- No setup instructions