AI Development Guidelines MCP Server

{ "version": "1.0.0", "build_time": "2025-10-27T18:00:46.607236", "documents": { "rules": "# Professional Development Rules\n\n## Code Quality Standards\n\n### 1. Code Organization\n- **Single Responsibility Principle**: Each function/class should have one clear purpose\n- **DRY (Don't Repeat Yourself)**: Extract common logic into reusable functions\n- **Clear Naming**: Use descriptive, meaningful names for variables, functions, and classes\n- **Consistent Structure**: Follow language-specific conventions and patterns\n\n### 2. Error Handling\n- **Never Fail Silently**: Always handle errors appropriately\n- **Specific Exceptions**: Catch specific exceptions, not broad try-except blocks\n- **Meaningful Error Messages**: Provide context about what went wrong and how to fix it\n- **Graceful Degradation**: Handle errors without crashing the entire application\n\n### 3. Security Best Practices\n- **Never Hardcode Secrets**: Use environment variables or secure vaults\n- **Input Validation**: Always validate and sanitize user input\n- **SQL Injection Prevention**: Use parameterized queries or ORMs\n- **Authentication & Authorization**: Implement proper access controls\n- **HTTPS/TLS**: Use secure connections for data transmission\n\n### 4. Performance Optimization\n- **Avoid Premature Optimization**: Write clear code first, optimize when needed\n- **Database Query Efficiency**: Use indexes, avoid N+1 queries\n- **Caching Strategy**: Cache expensive operations appropriately\n- **Async Operations**: Use async/await for I/O-bound operations\n- **Resource Management**: Properly close files, connections, and streams\n\n### 5. Code Documentation\n- **Docstrings**: Document all public functions, classes, and modules\n- **Type Hints**: Use type annotations in Python (or equivalent in other languages)\n- **Comments for Complex Logic**: Explain \"why\" not \"what\"\n- **README Files**: Provide clear setup and usage instructions\n- **API Documentation**: Document endpoints, parameters, and responses\n\n### 6. Testing Requirements\n- **Unit Tests**: Test individual functions and methods\n- **Integration Tests**: Test component interactions\n- **Edge Cases**: Test boundary conditions and error scenarios\n- **Test Coverage**: Aim for >80% code coverage for critical paths\n- **Mock External Dependencies**: Isolate tests from external services\n\n### 7. Version Control\n- **Atomic Commits**: Each commit should represent one logical change\n- **Descriptive Messages**: Write clear commit messages explaining the change\n- **Branch Strategy**: Use feature branches, keep main/master stable\n- **Code Reviews**: All code should be reviewed before merging\n- **Semantic Versioning**: Follow semver for releases (MAJOR.MINOR.PATCH)\n\n### 8. Code Style & Formatting\n- **Consistent Formatting**: Use linters and formatters (black, prettier, etc.)\n- **Line Length**: Keep lines under 88-120 characters\n- **Indentation**: Use consistent indentation (4 spaces for Python)\n- **Import Organization**: Group and sort imports logically\n- **Remove Dead Code**: Delete commented-out code and unused imports\n\n### 9. API Design\n- **RESTful Principles**: Use appropriate HTTP methods (GET, POST, PUT, DELETE)\n- **Versioning**: Version your APIs (/v1/, /v2/)\n- **Consistent Responses**: Standardize response formats\n- **Rate Limiting**: Implement rate limiting for public APIs\n- **Pagination**: Paginate large result sets\n\n### 10. Database Best Practices\n- **Normalization**: Normalize data to reduce redundancy\n- **Indexing**: Create indexes on frequently queried columns\n- **Migrations**: Use migration tools for schema changes\n- **Backups**: Regular automated backups\n- **Connection Pooling**: Reuse database connections\n\n## Python-Specific Rules\n\n### Code Style\n- Follow PEP 8 style guide\n- Use `snake_case` for variables and functions\n- Use `PascalCase` for classes\n- Use `UPPER_CASE` for constants\n\n### Best Practices\n- Use list comprehensions for simple transformations\n- Leverage context managers (`with` statements)\n- Use `pathlib` for file path operations\n- Prefer f-strings for string formatting\n- Use dataclasses or pydantic for data structures\n\n### Common Patterns\n```python\n# Use type hints\ndef process_data(items: list[dict]) -> list[str]:\n return [item['name'] for item in items]\n\n# Use context managers\nwith open('file.txt', 'r') as f:\n content = f.read()\n\n# Use dataclasses\nfrom dataclasses import dataclass\n\n@dataclass\nclass User:\n id: int\n name: str\n email: str\n```\n\n## JavaScript/TypeScript-Specific Rules\n\n### Code Style\n- Use `camelCase` for variables and functions\n- Use `PascalCase` for classes and components\n- Use `UPPER_CASE` for constants\n- Prefer `const` over `let`, never use `var`\n\n### Best Practices\n- Use async/await over callbacks\n- Leverage destructuring for objects and arrays\n- Use arrow functions appropriately\n- Implement proper error boundaries in React\n- Use TypeScript for type safety\n\n## Git Commit Message Convention\n\n```\n<type>(<scope>): <subject>\n\n<body>\n\n<footer>\n```\n\nTypes: feat, fix, docs, style, refactor, test, chore\n\nExample:\n```\nfeat(auth): add OAuth2 authentication\n\n- Implement OAuth2 flow with Google provider\n- Add user session management\n- Create protected route middleware\n\nCloses #123\n```\n\n## Code Review Checklist\n\n- [ ] Code follows style guidelines\n- [ ] All tests pass\n- [ ] New code has tests\n- [ ] No hardcoded secrets or credentials\n- [ ] Error handling is comprehensive\n- [ ] Documentation is updated\n- [ ] No TODO or FIXME comments left unresolved\n- [ ] Performance implications considered\n- [ ] Security vulnerabilities addressed\n- [ ] Backward compatibility maintained\n", "skills": "# Professional Development Skills & Best Practices\n\n## Core Development Skills\n\n### 1. Problem Decomposition\n**Breaking down complex problems into manageable pieces**\n\n- Start with the big picture, then break into smaller components\n- Identify dependencies between components\n- Create a clear execution plan\n- Tackle one piece at a time\n- Validate each piece before moving forward\n\n**Example Approach:**\n```\nLarge Feature \u2192 Components \u2192 Functions \u2192 Implementation\n```\n\n### 2. Debugging Methodology\n**Systematic approach to finding and fixing bugs**\n\n#### The Scientific Method\n1. **Reproduce**: Confirm the bug consistently occurs\n2. **Isolate**: Narrow down where the problem occurs\n3. **Hypothesize**: Form theories about the cause\n4. **Test**: Verify or disprove each hypothesis\n5. **Fix**: Implement the solution\n6. **Verify**: Ensure the fix works and doesn't break anything else\n\n#### Debugging Tools\n- Print/console statements for quick insights\n- Debugger breakpoints for step-through analysis\n- Logging for production debugging\n- Stack traces for error context\n- Unit tests to isolate issues\n\n### 3. Code Reading & Understanding\n**Effectively understanding existing codebases**\n\n#### Steps to Understand New Code\n1. Read the README and documentation first\n2. Understand the project structure and architecture\n3. Identify the entry point (main.py, index.js, etc.)\n4. Follow the flow of a typical request/operation\n5. Look for patterns and conventions\n6. Note dependencies and external services\n\n#### Questions to Ask\n- What problem does this code solve?\n- What are the main components?\n- How do components interact?\n- What are the data flows?\n- Where are the external dependencies?\n\n### 4. Refactoring Skills\n**Improving code without changing functionality**\n\n#### When to Refactor\n- Code duplication (DRY violation)\n- Functions longer than ~50 lines\n- Deeply nested conditionals\n- Poor naming or unclear intent\n- Performance bottlenecks\n- Before adding new features\n\n#### Safe Refactoring Steps\n1. Ensure tests exist (write them if needed)\n2. Make small, incremental changes\n3. Run tests after each change\n4. Commit working states frequently\n5. Use IDE refactoring tools when available\n\n#### Common Refactoring Patterns\n- Extract method/function\n- Rename for clarity\n- Extract class/module\n- Simplify conditionals\n- Remove dead code\n\n### 5. API Design Skills\n**Creating clean, intuitive interfaces**\n\n#### RESTful API Design\n```\nGET /users # List users\nGET /users/:id # Get specific user\nPOST /users # Create user\nPUT /users/:id # Update user\nDELETE /users/:id # Delete user\n```\n\n#### Good API Characteristics\n- **Consistent**: Predictable patterns across endpoints\n- **Intuitive**: Easy to understand without extensive docs\n- **Versioned**: Can evolve without breaking clients\n- **Well-documented**: Clear examples and descriptions\n- **Error-friendly**: Meaningful error messages\n\n### 6. Database Design Skills\n**Structuring data effectively**\n\n#### Key Principles\n- Normalize to reduce redundancy\n- Index frequently queried fields\n- Use appropriate data types\n- Consider query patterns when designing\n- Plan for scalability\n\n#### Common Patterns\n```sql\n-- One-to-Many\nCREATE TABLE users (\n id SERIAL PRIMARY KEY,\n username VARCHAR(50) UNIQUE\n);\n\nCREATE TABLE posts (\n id SERIAL PRIMARY KEY,\n user_id INTEGER REFERENCES users(id),\n content TEXT\n);\n\n-- Many-to-Many\nCREATE TABLE users_roles (\n user_id INTEGER REFERENCES users(id),\n role_id INTEGER REFERENCES roles(id),\n PRIMARY KEY (user_id, role_id)\n);\n```\n\n### 7. Testing Skills\n**Writing effective tests**\n\n#### Test Pyramid\n```\n /\\\n /UI\\ Few - Slow - Expensive\n /____\\\n /Integ-\\ Medium number\n /ration \\\n /__________\\\n/ Unit \\ Many - Fast - Cheap\n/______________\\\n```\n\n#### Good Test Characteristics\n- **Independent**: Tests don't depend on each other\n- **Repeatable**: Same results every time\n- **Fast**: Quick feedback loop\n- **Comprehensive**: Cover edge cases\n- **Readable**: Clear what's being tested\n\n#### Test Structure (Arrange-Act-Assert)\n```python\ndef test_user_creation():\n # Arrange\n username = \"testuser\"\n email = \"test@example.com\"\n \n # Act\n user = create_user(username, email)\n \n # Assert\n assert user.username == username\n assert user.email == email\n assert user.id is not None\n```\n\n### 8. Security Awareness\n**Building secure applications**\n\n#### Key Security Principles\n- **Least Privilege**: Grant minimum necessary permissions\n- **Defense in Depth**: Multiple layers of security\n- **Fail Securely**: Default to denying access\n- **Never Trust Input**: Validate and sanitize everything\n- **Keep Secrets Secret**: Use environment variables and vaults\n\n#### Common Vulnerabilities (OWASP Top 10)\n1. Injection (SQL, Command, etc.)\n2. Broken Authentication\n3. Sensitive Data Exposure\n4. XML External Entities (XXE)\n5. Broken Access Control\n6. Security Misconfiguration\n7. Cross-Site Scripting (XSS)\n8. Insecure Deserialization\n9. Using Components with Known Vulnerabilities\n10. Insufficient Logging & Monitoring\n\n### 9. Performance Optimization\n**Making applications fast and efficient**\n\n#### Optimization Strategy\n1. **Measure First**: Profile before optimizing\n2. **Identify Bottlenecks**: Focus on the slowest parts\n3. **Optimize Smartly**: Target high-impact areas\n4. **Measure Again**: Verify improvements\n5. **Consider Trade-offs**: Balance speed, memory, complexity\n\n#### Common Optimizations\n- Database query optimization (indexes, query structure)\n- Caching (Redis, in-memory, CDN)\n- Lazy loading and pagination\n- Async/parallel processing\n- Code-level optimizations (algorithms, data structures)\n\n### 10. Documentation Skills\n**Communicating through code and docs**\n\n#### Code Documentation\n```python\ndef calculate_discount(price: float, discount_percent: float) -> float:\n \"\"\"\n Calculate the discounted price.\n \n Args:\n price: Original price before discount\n discount_percent: Discount percentage (0-100)\n \n Returns:\n Final price after applying discount\n \n Raises:\n ValueError: If discount_percent is not between 0 and 100\n \n Example:\n >>> calculate_discount(100.0, 20.0)\n 80.0\n \"\"\"\n if not 0 <= discount_percent <= 100:\n raise ValueError(\"Discount must be between 0 and 100\")\n return price * (1 - discount_percent / 100)\n```\n\n#### README Structure\n```markdown\n# Project Name\n\nBrief description of what the project does\n\n## Features\n- Feature 1\n- Feature 2\n\n## Installation\nStep-by-step setup instructions\n\n## Usage\nCode examples\n\n## API Documentation\nEndpoint descriptions\n\n## Contributing\nHow to contribute\n\n## License\n```\n\n## Soft Skills for Developers\n\n### 1. Communication\n- Write clear commit messages and PR descriptions\n- Document complex decisions\n- Ask questions when unclear\n- Provide context in bug reports\n\n### 2. Collaboration\n- Review code constructively\n- Accept feedback graciously\n- Share knowledge with team\n- Help unblock teammates\n\n### 3. Time Management\n- Break work into small tasks\n- Estimate realistically\n- Focus on one thing at a time\n- Take breaks to maintain productivity\n\n### 4. Continuous Learning\n- Read documentation thoroughly\n- Study other people's code\n- Stay updated with best practices\n- Experiment with new technologies\n\n## Development Workflow\n\n### Daily Development Process\n```\n1. Pull latest changes\n2. Create feature branch\n3. Write failing test (TDD)\n4. Implement feature\n5. Make test pass\n6. Refactor if needed\n7. Run all tests\n8. Commit with clear message\n9. Push and create PR\n10. Address review feedback\n11. Merge when approved\n```\n\n### Project Kickoff Checklist\n- [ ] Understand requirements clearly\n- [ ] Design system architecture\n- [ ] Set up development environment\n- [ ] Configure linters and formatters\n- [ ] Set up CI/CD pipeline\n- [ ] Create project documentation\n- [ ] Define coding standards\n- [ ] Plan testing strategy\n\n## Tools Mastery\n\n### Essential Developer Tools\n- **Version Control**: Git (branching, merging, rebasing)\n- **Code Editor**: VS Code, PyCharm, etc. (shortcuts, extensions)\n- **Terminal**: Bash/Zsh (navigation, pipes, scripts)\n- **Debugger**: Language-specific debuggers\n- **Database Tools**: SQL clients, ORMs\n- **API Testing**: Postman, curl, httpie\n- **Package Managers**: pip, npm, cargo, etc.\n\n### Keyboard Shortcuts to Master\n- Navigate files quickly\n- Multi-cursor editing\n- Code completion and snippets\n- Refactoring shortcuts\n- Debugging controls\n- Terminal integration\n", "steering": "# AI Agent Steering Instructions\n\n## Core Principles for AI-Assisted Development\n\n### 1. Think Before Acting\n**Always analyze the problem thoroughly before writing code**\n\n- Understand the full context and requirements\n- Consider edge cases and potential issues\n- Plan the solution architecture\n- Identify potential pitfalls\n- Choose the right approach for the situation\n\n### 2. Follow Best Practices\n**Write production-quality code from the start**\n\n- Apply the rules from rules.md\n- Use established patterns and conventions\n- Consider security implications\n- Think about maintainability\n- Plan for scalability\n\n### 3. Be Explicit and Clear\n**Avoid ambiguity in code and communication**\n\n- Use descriptive variable and function names\n- Add comments for complex logic\n- Provide clear error messages\n- Document assumptions\n- Explain your reasoning\n\n## Code Generation Guidelines\n\n### Before Writing Code\n\n#### Checklist\n1. **Understand the requirement completely**\n - What is the exact goal?\n - What are the inputs and outputs?\n - What are the constraints?\n\n2. **Check existing codebase**\n - What patterns are already used?\n - What libraries are available?\n - What conventions should I follow?\n\n3. **Consider the context**\n - Is this a new feature or a fix?\n - Will this affect other parts of the system?\n - Are there performance implications?\n\n4. **Plan the solution**\n - What's the simplest approach?\n - What are alternative approaches?\n - What are the trade-offs?\n\n### While Writing Code\n\n#### Quality Standards\n- **Type Safety**: Use type hints/annotations\n- **Error Handling**: Handle exceptions appropriately\n- **Validation**: Validate all inputs\n- **Security**: Never expose secrets, sanitize inputs\n- **Readability**: Code should be self-documenting\n- **Testing**: Consider testability\n\n#### Code Structure\n```python\n# Good structure example\ndef process_user_data(user_id: int, data: dict) -> dict:\n \"\"\"\n Process user data with validation and error handling.\n \n Args:\n user_id: Unique identifier for the user\n data: Dictionary containing user data to process\n \n Returns:\n Processed data dictionary\n \n Raises:\n ValueError: If user_id is invalid or data is malformed\n \"\"\"\n # Validate inputs\n if user_id <= 0:\n raise ValueError(\"User ID must be positive\")\n \n if not isinstance(data, dict):\n raise ValueError(\"Data must be a dictionary\")\n \n # Process data\n try:\n processed = {\n 'user_id': user_id,\n 'name': data.get('name', '').strip(),\n 'email': data.get('email', '').lower(),\n 'timestamp': datetime.now().isoformat()\n }\n return processed\n except Exception as e:\n logger.error(f\"Error processing user {user_id}: {e}\")\n raise\n```\n\n### After Writing Code\n\n#### Self-Review Checklist\n- [ ] Code follows project conventions\n- [ ] All edge cases are handled\n- [ ] Error messages are helpful\n- [ ] No hardcoded values (use config/env vars)\n- [ ] Code is DRY (no unnecessary repetition)\n- [ ] Functions are focused and single-purpose\n- [ ] Type hints are present\n- [ ] Docstrings are complete\n- [ ] No security vulnerabilities\n- [ ] Performance is acceptable\n\n## Problem-Solving Framework\n\n### Step 1: Understand\n- Read the requirement carefully\n- Ask clarifying questions if needed\n- Identify the core problem\n- List all constraints\n\n### Step 2: Research\n- Check documentation\n- Look at similar implementations\n- Review best practices\n- Consider proven patterns\n\n### Step 3: Design\n- Sketch the solution\n- Identify components\n- Define interfaces\n- Plan error handling\n\n### Step 4: Implement\n- Start with the simplest working solution\n- Add complexity only when needed\n- Test as you go\n- Commit frequently\n\n### Step 5: Review\n- Check against requirements\n- Test edge cases\n- Review for security issues\n- Optimize if necessary\n\n### Step 6: Document\n- Add docstrings\n- Update README if needed\n- Comment complex logic\n- Create usage examples\n\n## Common Patterns & Anti-Patterns\n\n### \u2705 Good Patterns\n\n#### Configuration Management\n```python\n# Use environment variables or config files\nimport os\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\nAPI_KEY = os.getenv('API_KEY')\nDATABASE_URL = os.getenv('DATABASE_URL')\n```\n\n#### Error Handling\n```python\n# Specific, helpful error handling\ntry:\n user = get_user(user_id)\nexcept UserNotFoundError:\n logger.warning(f\"User {user_id} not found\")\n return {\"error\": \"User not found\"}, 404\nexcept DatabaseError as e:\n logger.error(f\"Database error: {e}\")\n return {\"error\": \"Internal server error\"}, 500\n```\n\n#### Dependency Injection\n```python\n# Make dependencies explicit\nclass UserService:\n def __init__(self, db: Database, cache: Cache):\n self.db = db\n self.cache = cache\n \n def get_user(self, user_id: int) -> User:\n # Try cache first\n cached = self.cache.get(f\"user:{user_id}\")\n if cached:\n return cached\n \n # Fetch from database\n user = self.db.get_user(user_id)\n self.cache.set(f\"user:{user_id}\", user)\n return user\n```\n\n### \u274c Anti-Patterns to Avoid\n\n#### Hardcoded Values\n```python\n# Bad\ndef send_email(to: str, subject: str):\n smtp.connect(\"smtp.gmail.com\", 587) # Hardcoded!\n smtp.login(\"myemail@gmail.com\", \"password123\") # Terrible!\n\n# Good\ndef send_email(to: str, subject: str):\n smtp.connect(config.SMTP_HOST, config.SMTP_PORT)\n smtp.login(config.SMTP_USER, os.getenv('SMTP_PASSWORD'))\n```\n\n#### Swallowing Exceptions\n```python\n# Bad\ntry:\n result = risky_operation()\nexcept:\n pass # Silent failure!\n\n# Good\ntry:\n result = risky_operation()\nexcept SpecificException as e:\n logger.error(f\"Operation failed: {e}\")\n raise # Re-raise or handle appropriately\n```\n\n#### God Objects/Functions\n```python\n# Bad - function does too much\ndef handle_user_request(request):\n # Validation\n # Authentication\n # Database operations\n # Business logic\n # Email sending\n # Logging\n # Response formatting\n # ... 200 lines later ...\n\n# Good - single responsibility\ndef handle_user_request(request):\n validate_request(request)\n user = authenticate(request)\n data = process_data(request.data)\n save_to_database(data)\n send_notification(user, data)\n return format_response(data)\n```\n\n## Context-Aware Development\n\n### For New Projects\n- Set up project structure following conventions\n- Initialize version control\n- Configure linters and formatters\n- Set up virtual environment/dependency management\n- Create README with setup instructions\n- Add .gitignore for the language/framework\n\n### For Existing Projects\n- Study the existing codebase first\n- Follow established patterns\n- Match the existing code style\n- Don't refactor unless asked\n- Respect architectural decisions\n- Add to existing documentation\n\n### For Bug Fixes\n- Reproduce the bug first\n- Understand the root cause\n- Write a test that fails\n- Fix the bug\n- Verify the test passes\n- Check for similar bugs elsewhere\n\n### For New Features\n- Understand the use case\n- Design the API/interface\n- Write tests first (TDD)\n- Implement incrementally\n- Document the feature\n- Update relevant documentation\n\n## Communication Guidelines\n\n### When Explaining Code\n- Start with the high-level purpose\n- Explain the approach\n- Highlight important details\n- Mention trade-offs or limitations\n- Provide usage examples\n\n### When Asking for Clarification\n- Be specific about what's unclear\n- Provide context\n- Suggest possible interpretations\n- Ask focused questions\n\n### When Reporting Issues\n- Describe expected behavior\n- Describe actual behavior\n- Provide steps to reproduce\n- Include relevant error messages\n- Suggest possible causes if known\n\n## Continuous Improvement\n\n### Learning from Code\n- Study well-written codebases\n- Understand why certain patterns are used\n- Note new techniques and approaches\n- Question and validate best practices\n\n### Adapting to Context\n- Recognize when rules should be bent\n- Understand the \"why\" behind rules\n- Apply judgment based on situation\n- Balance idealism with pragmatism\n\n### Iterative Refinement\n- Start simple, add complexity as needed\n- Refactor as understanding improves\n- Optimize based on real metrics\n- Improve based on feedback\n\n## Decision-Making Framework\n\n### When Choosing Technologies\n1. **Project Requirements**: What does the project actually need?\n2. **Team Familiarity**: What does the team know?\n3. **Community Support**: Is it well-maintained and documented?\n4. **Performance**: Does it meet performance requirements?\n5. **Long-term Viability**: Will it be maintained in the future?\n\n### When Deciding on Architecture\n1. **Current Needs**: Solve today's problems\n2. **Known Future Needs**: Plan for clear upcoming requirements\n3. **Flexibility**: Allow for unforeseen changes\n4. **Simplicity**: Choose the simplest solution that works\n5. **Maintainability**: Can others understand and modify it?\n\n### When Optimizing\n1. **Measure First**: Don't guess at bottlenecks\n2. **Cost-Benefit**: Is the optimization worth the complexity?\n3. **User Impact**: Will users notice the improvement?\n4. **Maintenance Burden**: Does it make the code harder to maintain?\n5. **Alternative Solutions**: Are there simpler ways to achieve the goal?\n\n## Summary\n\nAs an AI agent assisting with development:\n1. **Understand** the context fully before acting\n2. **Follow** established best practices and patterns\n3. **Write** clean, secure, maintainable code\n4. **Test** your solutions thoroughly\n5. **Document** your code and decisions\n6. **Learn** from each interaction\n7. **Adapt** to the specific project needs\n8. **Communicate** clearly and helpfully\n\nRemember: The goal is to write code that is correct, secure, maintainable, and appropriate for the context. Quality over speed, clarity over cleverness, and always think about the humans who will read and maintain your code.\n" }, "metadata": { "rules_size": 5513, "skills_size": 8576, "steering_size": 9960, "total_size": 24049 } }