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/entities/__init__.py

@@ -1,4 +1,8 @@
-"""Domain entities."""
+"""Domain entities.
+
+This module re-exports all domain entities that represent
+core business objects with identity.
+"""
 
 from app.domain.entities.base import BaseEntity
 from app.domain.entities.post import Post

app/domain/entities/base.py

@@ -1,4 +1,9 @@
-"""Base entity for DDD domain layer."""
+"""Base entity for DDD domain layer.
+
+This module provides the foundational BaseEntity class that all domain
+entities must inherit from. It implements common entity patterns including
+identity management, equality comparison, and timestamp tracking.
+"""
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
@@ -9,25 +14,62 @@ from uuid import UUID, uuid4
 
 @dataclass(kw_only=True)
 class BaseEntity(ABC):
-    """Base class for all domain entities."""
+    """Base class for all domain entities.
+
+    Provides common functionality for domain entities including unique
+    identification, creation/update timestamps, and equality comparison
+    based on identity.
+
+    Attributes:
+        id: Unique identifier for the entity, automatically generated.
+        created_at: Timestamp when the entity was created.
+        updated_at: Timestamp when the entity was last updated.
+
+    Example:
+        >>> class User(BaseEntity):
+        ...     name: str
+        ...     def to_dict(self) -> dict[str, Any]:
+        ...         return {"id": str(self.id), "name": self.name}
+    """
 
     id: UUID = field(default_factory=uuid4)
     created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
     updated_at: datetime = field(default_factory=lambda: datetime.now(UTC))
 
     def __eq__(self, other: object) -> bool:
+        """Compare entities by identity.
+
+        Args:
+            other: Another object to compare with.
+
+        Returns:
+            True if both objects are BaseEntity instances with same ID.
+        """
         if not isinstance(other, BaseEntity):
             return NotImplemented
         return self.id == other.id
 
     def __hash__(self) -> int:
+        """Get hash based on entity identity.
+
+        Returns:
+            Hash of the entity ID.
+        """
         return hash(self.id)
 
     def touch(self) -> None:
-        """Update the updated_at timestamp."""
+        """Update the updated_at timestamp.
+
+        Should be called whenever the entity is modified to track
+        the last modification time.
+        """
         self.updated_at = datetime.now(UTC)
 
     @abstractmethod
     def to_dict(self) -> dict[str, Any]:
-        """Convert entity to dictionary."""
+        """Convert entity to dictionary representation.
+
+        Returns:
+            Dictionary containing all entity attributes.
+        """
         ...

app/domain/entities/post.py

@@ -1,4 +1,9 @@
-"""Domain entity for Blog Post."""
+"""Domain entity for Blog Post.
+
+This module defines the Post aggregate root entity that encapsulates
+all business logic related to blog posts including publishing, content
+management, and tag operations.
+"""
 
 from dataclasses import dataclass, field
 from typing import Any
@@ -11,7 +16,28 @@ from app.domain.value_objects.title import Title
 
 @dataclass(kw_only=True)
 class Post(BaseEntity):
-    """Blog post domain entity."""
+    """Blog post domain entity.
+
+    Represents a blog post with title, content, slug, and metadata.
+    Encapsulates business logic for post lifecycle management.
+
+    Attributes:
+        title: Post title value object with validation.
+        content: Post content value object with validation.
+        slug: URL-friendly identifier generated from title.
+        author_id: Identifier of the post author.
+        published: Publication status flag.
+        tags: List of tags associated with the post.
+
+    Example:
+        >>> post = Post.create(
+        ...     title_str="My First Post",
+        ...     content_str="This is the content...",
+        ...     author_id="user-123",
+        ...     tags=["python", "fastapi"]
+        ... )
+        >>> post.publish()
+    """
 
     title: Title
     content: Content
@@ -21,40 +47,66 @@ class Post(BaseEntity):
     tags: list[str] = field(default_factory=list)
 
     def publish(self) -> None:
-        """Publish the post."""
+        """Publish the post.
+
+        Sets the published flag to True and updates the timestamp.
+        """
         self.published = True
         self.touch()
 
     def unpublish(self) -> None:
-        """Unpublish the post."""
+        """Unpublish the post.
+
+        Sets the published flag to False and updates the timestamp.
+        """
         self.published = False
         self.touch()
 
     def update_content(self, content: Content) -> None:
-        """Update post content."""
+        """Update post content.
+
+        Args:
+            content: New content value object.
+        """
         self.content = content
         self.touch()
 
     def update_title(self, title: Title) -> None:
-        """Update post title and regenerate slug."""
+        """Update post title and regenerate slug.
+
+        Args:
+            title: New title value object.
+        """
         self.title = title
         self.slug = Slug.from_title(title.value)
         self.touch()
 
     def add_tag(self, tag: str) -> None:
-        """Add a tag to the post."""
+        """Add a tag to the post.
+
+        Args:
+            tag: Tag string to add. Only adds if not already present.
+        """
         if tag not in self.tags:
             self.tags.append(tag)
             self.touch()
 
     def remove_tag(self, tag: str) -> None:
-        """Remove a tag from the post."""
+        """Remove a tag from the post.
+
+        Args:
+            tag: Tag string to remove. Only removes if present.
+        """
         if tag in self.tags:
             self.tags.remove(tag)
             self.touch()
 
     def to_dict(self) -> dict[str, Any]:
-        """Convert entity to dictionary."""
+        """Convert entity to dictionary.
+
+        Returns:
+            Dictionary representation with all post attributes.
+        """
         return {
             "id": str(self.id),
             "title": self.title.value,
@@ -75,7 +127,17 @@ class Post(BaseEntity):
         author_id: str,
         tags: list[str] | None = None,
     ) -> "Post":
-        """Factory method to create a new post."""
+        """Factory method to create a new post.
+
+        Args:
+            title_str: Title string for the post.
+            content_str: Content string for the post.
+            author_id: Identifier of the post author.
+            tags: Optional list of tags.
+
+        Returns:
+            New Post instance with validated value objects.
+        """
         title = Title(title_str)
         content = Content(content_str)
         slug = Slug.from_title(title_str)