Skip to content

Claude: Next steps #500

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AkhileshNegi merged 5 commits into from
Dec 17, 2025
Merged

Claude: Next steps #500

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5ddab81
claude updates
AkhileshNegi Dec 15, 2025
8c31040
Merge branch 'main' into enhancement/claude-next-steps
AkhileshNegi Dec 16, 2025
84b9d0a
updated migration command
AkhileshNegi Dec 16, 2025
a8e0e27
making it concise
AkhileshNegi Dec 17, 2025
97515e4
add step to add typehint
AkhileshNegi Dec 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 49 additions & 2 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ fastapi run --reload app/main.py
# Run pre-commit hooks
uv run pre-commit run --all-files

# Generate database migration
alembic revision --autogenerate -m 'Description'
# Generate database migration (rev-id should be latest existing revision ID + 1)
alembic revision --autogenerate -m "Description" --rev-id 040

# Seed database with test data
uv run python -m app.seed_data.seed_data
Expand Down Expand Up @@ -90,3 +90,50 @@ The application uses different environment files:

- Python 3.11+ with type hints
- Pre-commit hooks for linting and formatting

## Coding Conventions

### Type Hints

Always add type hints to all function parameters and return values.

### Logging Format

Prefix all log messages with the function name in square brackets.

```python
logger.info(f"[function_name] Message {mask_string(sensitive_value)}")
```

### Database Column Comments

Use sa_column_kwargs["comment"] to describe database columns, especially when the purpose isn’t obvious. This helps non-developers understand column purposes directly from the database schema:

```python
field_name: int = Field(
foreign_key="table.id",
nullable=False,
ondelete="CASCADE",
sa_column_kwargs={"comment": "What this column represents"}
)
```

Prioritize comments for:
- Columns with non-obvious purposes
- Status/type fields (document valid values)
- JSON/metadata columns (describe expected structure)
- Foreign keys (clarify the relationship)

### Endpoint Documentation

Load Swagger descriptions from external markdown files instead of inline strings:

```python
@router.post(
"/endpoint",
description=load_description("domain/action.md"),
response_model=APIResponse[ResponseModel],
)
```

Store documentation files in `backend/app/api/docs/<domain>/<action>.md`
Comment on lines +127 to +139
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Search for the `load_description` function definition and usage in the codebase

# Search for the function definition
echo "=== Searching for load_description function definition ==="
rg -n 'def\s+load_description' --type=py

# Search for imports or references to the function
echo -e "\n=== Searching for imports/references to load_description ==="
rg -n 'load_description' --type=py -C 2

Repository: ProjectTech4DevAI/kaapi-backend

Length of output: 30872

🏁 Script executed:

#!/bin/bash

echo "=== Full implementation of load_description function ==="
sed -n '391,410p' backend/app/utils.py

echo -e "\n=== Check if docs directory exists ==="
ls -la backend/app/api/docs/ 2>/dev/null || echo "Directory not found"

echo -e "\n=== Check docs directory structure ==="
find backend/app/api/docs/ -type f -name "*.md" 2>/dev/null | head -20 || echo "No markdown files found"

echo -e "\n=== Check for any documentation in utils.py about load_description ==="
rg -B5 -A15 'def load_description' backend/app/utils.py --type=py

Repository: ProjectTech4DevAI/kaapi-backend

Length of output: 2904

Add docstring to load_description() function for clarity.

The load_description() helper function exists in backend/app/utils.py and is properly accessible. It's already imported and used across 17+ route files following the pattern documented in CLAUDE.md. However, the function lacks a docstring explaining its purpose and usage. Adding documentation would improve discoverability and make it easier for developers to understand the expected path format without needing to examine the implementation.

🤖 Prompt for AI Agents 
In CLAUDE.md around lines 130 to 142: add a descriptive docstring to the
load_description() helper in backend/app/utils.py that explains its purpose
(loading external Markdown strings for route descriptions), the expected
parameter(s) (path relative to backend/app/api/docs, accepted formats like
"domain/action.md" or subpaths), return type (string containing markdown),
behavior on missing files or IO errors (exceptions raised or default fallback),
and a short usage example showing how to call it from router decorators; keep it
concise, follow project docstring style, and include parameter/return
annotations and any raised exceptions.