docs: add AI code generation requirements and comprehensive Google-style docstrings

- Add AI code generation requirements to AGENTS.md
- Add module-level docstrings to all 46 Python modules
- Add detailed Google-style docstrings to all classes and functions
- Remove all inline comments following self-documenting code principle
- Include Args, Returns, Raises sections in function docstrings
- Add Attributes and Examples sections to class docstrings

app/domain/repositories/__init__.py

@@ -1,4 +1,8 @@
-"""Repository interfaces."""
+"""Repository interfaces.
+
+This module re-exports all repository interfaces that define
+the contract for data access operations.
+"""
 
 from app.domain.repositories.base import Repository
 from app.domain.repositories.post import PostRepository

app/domain/repositories/base.py

@@ -1,4 +1,8 @@
-"""Base repository interface for DDD."""
+"""Base repository interface for DDD.
+
+This module defines the generic repository pattern interface that all
+repository implementations must follow. Provides standard CRUD operations.
+"""
 
 from abc import ABC, abstractmethod
 from typing import Generic, TypeVar
@@ -10,34 +14,76 @@ T = TypeVar("T", bound=BaseEntity)
 
 
 class Repository(ABC, Generic[T]):
-    """Generic repository interface."""
+    """Generic repository interface.
+
+    Defines the contract for repository implementations. All repositories
+    must provide standard CRUD operations for their entity type.
+
+    Type Parameters:
+        T: Entity type that must inherit from BaseEntity.
+
+    Example:
+        >>> class PostRepository(Repository[Post]):
+        ...     async def get_by_id(self, entity_id: UUID) -> Post | None:
+        ...         ...
+    """
 
     @abstractmethod
     async def get_by_id(self, entity_id: UUID) -> T | None:
-        """Get entity by ID."""
+        """Get entity by ID.
+
+        Args:
+            entity_id: Unique identifier of the entity.
+
+        Returns:
+            Entity instance if found, None otherwise.
+        """
         ...
 
     @abstractmethod
     async def get_all(self) -> list[T]:
-        """Get all entities."""
+        """Get all entities.
+
+        Returns:
+            List of all entity instances.
+        """
         ...
 
     @abstractmethod
     async def add(self, entity: T) -> None:
-        """Add new entity."""
+        """Add new entity.
+
+        Args:
+            entity: Entity instance to add.
+        """
         ...
 
     @abstractmethod
     async def update(self, entity: T) -> None:
-        """Update existing entity."""
+        """Update existing entity.
+
+        Args:
+            entity: Entity instance with updated data.
+        """
         ...
 
     @abstractmethod
     async def delete(self, entity_id: UUID) -> None:
-        """Delete entity by ID."""
+        """Delete entity by ID.
+
+        Args:
+            entity_id: Unique identifier of the entity to delete.
+        """
         ...
 
     @abstractmethod
     async def exists(self, entity_id: UUID) -> bool:
-        """Check if entity exists."""
+        """Check if entity exists.
+
+        Args:
+            entity_id: Unique identifier of the entity.
+
+        Returns:
+            True if entity exists, False otherwise.
+        """
         ...

app/domain/repositories/post.py

@@ -1,4 +1,8 @@
-"""Post repository interface."""
+"""Post repository interface.
+
+This module extends the base repository interface with post-specific
+query methods including slug lookup, author filtering, and search.
+"""
 
 from abc import abstractmethod
 
@@ -7,11 +11,27 @@ from app.domain.repositories.base import Repository
 
 
 class PostRepository(Repository[Post]):
-    """Repository interface for Blog Posts."""
+    """Repository interface for Blog Posts.
+
+    Extends the generic repository with post-specific operations
+    including slug-based lookup, author filtering, tag filtering,
+    and full-text search capabilities.
+
+    Example:
+        >>> posts = await repo.get_by_author("user-123", limit=10)
+        >>> exists = await repo.slug_exists("my-first-post")
+    """
 
     @abstractmethod
     async def get_by_slug(self, slug: str) -> Post | None:
-        """Get post by slug."""
+        """Get post by slug.
+
+        Args:
+            slug: URL-friendly slug identifier.
+
+        Returns:
+            Post instance if found, None otherwise.
+        """
         ...
 
     @abstractmethod
@@ -21,7 +41,16 @@ class PostRepository(Repository[Post]):
         limit: int | None = None,
         offset: int | None = None,
     ) -> list[Post]:
-        """Get all posts by author."""
+        """Get all posts by author.
+
+        Args:
+            author_id: Identifier of the author.
+            limit: Maximum number of posts to return.
+            offset: Number of posts to skip.
+
+        Returns:
+            List of posts by the specified author.
+        """
         ...
 
     @abstractmethod
@@ -30,7 +59,15 @@ class PostRepository(Repository[Post]):
         limit: int | None = None,
         offset: int | None = None,
     ) -> list[Post]:
-        """Get all published posts."""
+        """Get all published posts.
+
+        Args:
+            limit: Maximum number of posts to return.
+            offset: Number of posts to skip.
+
+        Returns:
+            List of published posts.
+        """
         ...
 
     @abstractmethod
@@ -40,12 +77,28 @@ class PostRepository(Repository[Post]):
         limit: int | None = None,
         offset: int | None = None,
     ) -> list[Post]:
-        """Get posts by tag."""
+        """Get posts by tag.
+
+        Args:
+            tag: Tag to filter by.
+            limit: Maximum number of posts to return.
+            offset: Number of posts to skip.
+
+        Returns:
+            List of posts with the specified tag.
+        """
         ...
 
     @abstractmethod
     async def slug_exists(self, slug: str) -> bool:
-        """Check if slug already exists."""
+        """Check if slug already exists.
+
+        Args:
+            slug: Slug to check for existence.
+
+        Returns:
+            True if slug exists, False otherwise.
+        """
         ...
 
     @abstractmethod
@@ -55,5 +108,14 @@ class PostRepository(Repository[Post]):
         limit: int | None = None,
         offset: int | None = None,
     ) -> list[Post]:
-        """Search posts by query string."""
+        """Search posts by query string.
+
+        Args:
+            query: Search query string.
+            limit: Maximum number of posts to return.
+            offset: Number of posts to skip.
+
+        Returns:
+            List of posts matching the search query.
+        """
         ...