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/presentation/api/v1/posts.py

@@ -1,4 +1,8 @@
-"""Posts API routes."""
+"""Posts API routes.
+
+This module defines FastAPI routes for blog post operations.
+Implements CRUD endpoints with authentication and authorization.
+"""
 
 from uuid import UUID
 
@@ -39,7 +43,16 @@ async def create_post(
     use_case: CreatePostDep,
     current_user_id: CurrentUserDep,
 ) -> PostResponseSchema:
-    """Create a new blog post."""
+    """Create a new blog post.
+
+    Args:
+        schema: Post creation data.
+        use_case: CreatePostUseCase dependency.
+        current_user_id: Authenticated user ID.
+
+    Returns:
+        PostResponseSchema with created post data.
+    """
     dto = CreatePostDTO(
         title=schema.title,
         content=schema.content,
@@ -65,19 +78,22 @@ async def list_posts(
     """Get blog posts with optional filtering and pagination.
 
     Args:
+        use_case: ListPostsUseCase dependency.
+        role: Current user role.
         include_unpublished: If True, returns all posts including drafts.
-                            Only admins can use this parameter.
+            Only admins can use this parameter.
         limit: Maximum number of posts to return (default: 10, max: 100).
         offset: Number of posts to skip (default: 0).
 
+    Returns:
+        PostListResponseSchema with paginated posts.
+
     Raises:
         ForbiddenException: If non-admin tries to include unpublished posts.
     """
-    # Clamp limit to reasonable range
     limit = max(1, min(limit, 100))
     offset = max(0, offset)
 
-    # Check permissions for unpublished posts
     if include_unpublished:
         if not has_permission(role, Permission.POST_READ_UNPUBLISHED):
             raise ForbiddenException("Only admins can view unpublished posts")
@@ -97,7 +113,14 @@ async def list_posts(
 async def list_published_posts(
     use_case: ListPostsDep,
 ) -> PostListResponseSchema:
-    """Get all published blog posts."""
+    """Get all published blog posts.
+
+    Args:
+        use_case: ListPostsUseCase dependency.
+
+    Returns:
+        PostListResponseSchema with published posts.
+    """
     results = await use_case.published_posts()
     items = [PostResponseSchema(**r.__dict__) for r in results]
     return PostListResponseSchema(items=items, total=len(items))
@@ -112,7 +135,15 @@ async def search_posts(
     query: str,
     use_case: ListPostsDep,
 ) -> PostListResponseSchema:
-    """Search posts by query."""
+    """Search posts by query.
+
+    Args:
+        query: Search query string.
+        use_case: ListPostsUseCase dependency.
+
+    Returns:
+        PostListResponseSchema with matching posts.
+    """
     results = await use_case.search(query)
     items = [PostResponseSchema(**r.__dict__) for r in results]
     return PostListResponseSchema(items=items, total=len(items))
@@ -127,7 +158,15 @@ async def get_posts_by_tag(
     tag: str,
     use_case: ListPostsDep,
 ) -> PostListResponseSchema:
-    """Get posts by tag."""
+    """Get posts by tag.
+
+    Args:
+        tag: Tag to filter by.
+        use_case: ListPostsUseCase dependency.
+
+    Returns:
+        PostListResponseSchema with tagged posts.
+    """
     results = await use_case.by_tag(tag)
     items = [PostResponseSchema(**r.__dict__) for r in results]
     return PostListResponseSchema(items=items, total=len(items))
@@ -142,7 +181,15 @@ async def get_posts_by_author(
     author_id: str,
     use_case: ListPostsDep,
 ) -> PostListResponseSchema:
-    """Get posts by author."""
+    """Get posts by author.
+
+    Args:
+        author_id: Author identifier.
+        use_case: ListPostsUseCase dependency.
+
+    Returns:
+        PostListResponseSchema with author's posts.
+    """
     results = await use_case.by_author(author_id)
     items = [PostResponseSchema(**r.__dict__) for r in results]
     return PostListResponseSchema(items=items, total=len(items))
@@ -157,7 +204,15 @@ async def get_post(
     post_id: UUID,
     use_case: GetPostDep,
 ) -> PostResponseSchema:
-    """Get a post by its ID."""
+    """Get a post by its ID.
+
+    Args:
+        post_id: Unique post identifier.
+        use_case: GetPostUseCase dependency.
+
+    Returns:
+        PostResponseSchema with post data.
+    """
     result = await use_case.by_id(post_id)
     return PostResponseSchema(**result.__dict__)
 
@@ -171,7 +226,15 @@ async def get_post_by_slug(
     slug: str,
     use_case: GetPostDep,
 ) -> PostResponseSchema:
-    """Get a post by its slug."""
+    """Get a post by its slug.
+
+    Args:
+        slug: URL-friendly slug identifier.
+        use_case: GetPostUseCase dependency.
+
+    Returns:
+        PostResponseSchema with post data.
+    """
     result = await use_case.by_slug(slug)
     return PostResponseSchema(**result.__dict__)
 
@@ -187,7 +250,17 @@ async def update_post(
     use_case: UpdatePostDep,
     current_user_id: CurrentUserDep,
 ) -> PostResponseSchema:
-    """Update a post."""
+    """Update a post.
+
+    Args:
+        post_id: Unique post identifier.
+        schema: Update data.
+        use_case: UpdatePostUseCase dependency.
+        current_user_id: Authenticated user ID.
+
+    Returns:
+        PostResponseSchema with updated post data.
+    """
     dto = UpdatePostDTO(
         title=schema.title,
         content=schema.content,
@@ -207,7 +280,13 @@ async def delete_post(
     use_case: DeletePostDep,
     current_user_id: CurrentUserDep,
 ) -> None:
-    """Delete a post."""
+    """Delete a post.
+
+    Args:
+        post_id: Unique post identifier.
+        use_case: DeletePostUseCase dependency.
+        current_user_id: Authenticated user ID.
+    """
     await use_case.execute(post_id, current_user_id)
 
 
@@ -221,7 +300,16 @@ async def publish_post(
     use_case: PublishPostDep,
     current_user_id: CurrentUserDep,
 ) -> PostResponseSchema:
-    """Publish a post."""
+    """Publish a post.
+
+    Args:
+        post_id: Unique post identifier.
+        use_case: PublishPostUseCase dependency.
+        current_user_id: Authenticated user ID.
+
+    Returns:
+        PostResponseSchema with published post data.
+    """
     result = await use_case.publish(post_id, current_user_id)
     return PostResponseSchema(**result.__dict__)
 
@@ -236,6 +324,15 @@ async def unpublish_post(
     use_case: PublishPostDep,
     current_user_id: CurrentUserDep,
 ) -> PostResponseSchema:
-    """Unpublish a post."""
+    """Unpublish a post.
+
+    Args:
+        post_id: Unique post identifier.
+        use_case: PublishPostUseCase dependency.
+        current_user_id: Authenticated user ID.
+
+    Returns:
+        PostResponseSchema with unpublished post data.
+    """
     result = await use_case.unpublish(post_id, current_user_id)
     return PostResponseSchema(**result.__dict__)