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/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.
+        """
         ...