aios-core/.aios-core/infrastructure/templates/project-docs/coding-standards-tmpl.md

Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework

# {{PROJECT_NAME}} Coding Standards

> **Auto-generated by AIOS** on {{GENERATED_DATE}}
> **Mode:** {{INSTALLATION_MODE}}
> **Tech Stack:** {{TECH_STACK}}

## Overview

This document defines the coding standards and conventions for **{{PROJECT_NAME}}**.

---

{{#if IS_NODE}}
## JavaScript/TypeScript Standards

### Language Version

- **ECMAScript:** ES2022+
- **TypeScript:** {{TYPESCRIPT_VERSION}} (if applicable)
- **Node.js:** {{NODE_VERSION}}

### Formatting

| Rule | Value |
|------|-------|
| Indentation | 2 spaces |
| Quotes | Single quotes `'` |
| Semicolons | {{SEMICOLONS}} |
| Max line length | 100 characters |
| Trailing commas | ES5 compatible |

### ESLint Configuration

```javascript
// .eslintrc.js
module.exports = {
  env: {
    node: true,
    es2022: true,
    jest: true,
  },
  extends: [
    'eslint:recommended',
{{#if IS_TYPESCRIPT}}
    '@typescript-eslint/recommended',
{{/if}}
  ],
  parserOptions: {
    ecmaVersion: 2022,
    sourceType: 'module',
  },
  rules: {
    'indent': ['error', 2],
    'quotes': ['error', 'single'],
    'semi': ['error', '{{SEMICOLONS_RULE}}'],
    'no-unused-vars': 'warn',
    'no-console': 'warn',
  },
};
```

### Prettier Configuration

```json
{
  "semi": {{PRETTIER_SEMI}},
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100
}
```

### Naming Conventions

| Type | Convention | Example |
|------|------------|---------|
| Variables | camelCase | `userName` |
| Constants | SCREAMING_SNAKE | `MAX_RETRIES` |
| Functions | camelCase | `getUserById()` |
| Classes | PascalCase | `UserService` |
| Files | kebab-case | `user-service.js` |
| React Components | PascalCase | `UserProfile.tsx` |

### Function Guidelines

```javascript
/**
 * Short description of function purpose
 *
 * @param {string} userId - User identifier
 * @param {Object} options - Configuration options
 * @returns {Promise<User>} The user object
 * @throws {NotFoundError} When user doesn't exist
 */
async function getUserById(userId, options = {}) {
  // Implementation
}
```

### Import Order

1. Node.js built-in modules
2. External dependencies (npm packages)
3. Internal modules (absolute paths)
4. Relative imports
5. Type imports (TypeScript)

```javascript
// 1. Built-in
const fs = require('fs');
const path = require('path');

// 2. External
const express = require('express');
const lodash = require('lodash');

// 3. Internal
const { config } = require('@/config');
const { UserService } = require('@/services/user');

// 4. Relative
const { helper } = require('./utils');
```
{{/if}}

{{#if IS_PYTHON}}
## Python Standards

### Language Version

- **Python:** {{PYTHON_VERSION}}
- **Package Manager:** pip / poetry

### Formatting

| Rule | Value |
|------|-------|
| Indentation | 4 spaces |
| Max line length | 88 characters (Black default) |
| Quotes | Double quotes `"` |
| Docstring style | Google style |

### Black Configuration

```toml
# pyproject.toml
[tool.black]
line-length = 88
target-version = ['py{{PYTHON_SHORT_VERSION}}']
include = '\.pyi?$'
```

### Flake8 Configuration

```ini
# .flake8
[flake8]
max-line-length = 88
extend-ignore = E203, W503
exclude = .git,__pycache__,build,dist
```

### Naming Conventions

| Type | Convention | Example |
|------|------------|---------|
| Variables | snake_case | `user_name` |
| Constants | SCREAMING_SNAKE | `MAX_RETRIES` |
| Functions | snake_case | `get_user_by_id()` |
| Classes | PascalCase | `UserService` |
| Files | snake_case | `user_service.py` |
| Private | Leading underscore | `_internal_method()` |

### Function Guidelines

```python
def get_user_by_id(user_id: str, options: dict = None) -> User:
    """Short description of function purpose.

    Args:
        user_id: User identifier
        options: Configuration options

    Returns:
        The user object

    Raises:
        NotFoundError: When user doesn't exist
    """
    # Implementation
    pass
```

### Import Order

1. Standard library imports
2. Related third-party imports
3. Local application imports

```python
# 1. Standard library
import os
import sys
from pathlib import Path

# 2. Third-party
import requests
from fastapi import FastAPI

# 3. Local
from {{PYTHON_PACKAGE_NAME}}.config import settings
from {{PYTHON_PACKAGE_NAME}}.services.user import UserService
```
{{/if}}

{{#if IS_GO}}
## Go Standards

### Language Version

- **Go:** {{GO_VERSION}}

### Formatting

- Use `gofmt` for all formatting
- Use `goimports` for import management

### Naming Conventions

| Type | Convention | Example |
|------|------------|---------|
| Variables | camelCase | `userName` |
| Constants | PascalCase or camelCase | `MaxRetries` |
| Functions (exported) | PascalCase | `GetUserByID` |
| Functions (private) | camelCase | `getUserByID` |
| Packages | lowercase | `userservice` |
| Files | snake_case | `user_service.go` |

### Function Guidelines

```go
// GetUserByID retrieves a user by their unique identifier.
//
// It returns the user and any error encountered.
func GetUserByID(ctx context.Context, userID string) (*User, error) {
    // Implementation
}
```

### Import Order

1. Standard library
2. Third-party packages
3. Local packages

```go
import (
    // Standard library
    "context"
    "fmt"

    // Third-party
    "github.com/gin-gonic/gin"

    // Local
    "{{GO_MODULE}}/internal/config"
    "{{GO_MODULE}}/internal/services"
)
```
{{/if}}

---

## Common Standards (All Languages)

### Error Handling

- Always handle errors explicitly
- Provide meaningful error messages
- Include context in error messages
- Use appropriate error types/codes

### Comments

- Write comments that explain "why", not "what"
- Keep comments up-to-date with code
- Use JSDoc/docstrings for public APIs
- Avoid commented-out code in commits

### Git Commit Messages

Follow conventional commits:

```
<type>(<scope>): <subject>

<body>

<footer>
```

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`

Example:
```
feat(auth): add OAuth2 login support

- Implement Google OAuth provider
- Add token refresh mechanism
- Update user model with OAuth fields

Closes #123
```

### Code Review Guidelines

1. **Functionality:** Does it work as intended?
2. **Readability:** Is it easy to understand?
3. **Maintainability:** Is it easy to modify?
4. **Performance:** Are there obvious bottlenecks?
5. **Security:** Are there vulnerabilities?
6. **Tests:** Is it adequately tested?

---

## Tools & Automation

### Pre-commit Hooks

The project uses pre-commit hooks for:
- Linting
- Formatting
- Type checking (if applicable)

### CI/CD Quality Gates

All PRs must pass:
{{#each QUALITY_GATES}}
- [ ] {{this}}
{{/each}}

---

*Generated by AIOS Documentation Integrity System*
*Template Version: 1.0.0*