122 lines
3.1 KiB
Markdown
122 lines
3.1 KiB
Markdown
# Development Guide for Agentic Coding Agents
|
|
|
|
## Build/Lint/Test Commands
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Install dependencies with Poetry
|
|
poetry install
|
|
|
|
# Install pre-commit hooks
|
|
pre-commit install
|
|
```
|
|
|
|
### Linting and Formatting
|
|
|
|
```bash
|
|
# Run all pre-commit checks (linting, formatting, type checking)
|
|
pre-commit run --all-files
|
|
|
|
# Run specific linters
|
|
ruff check . # Python linting
|
|
ruff format . # Python formatting
|
|
mypy . # Type checking
|
|
yamllint . # YAML linting
|
|
markdownlint . # Markdown linting
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Manual testing approach - run individual commands to test functionality
|
|
# Test schedule fetching
|
|
myice schedule --days 7
|
|
|
|
# Test mobile login
|
|
myice mobile-login
|
|
|
|
# Test specific command help
|
|
myice search --help
|
|
|
|
# Test web API (run in background)
|
|
poetry run fastapi run myice/webapi.py &
|
|
|
|
# Run a single pre-commit hook on specific file
|
|
pre-commit run ruff --files myice/myice.py
|
|
pre-commit run ruff-format --files myice/webapi.py
|
|
pre-commit run mypy --files myice/myice.py
|
|
```
|
|
|
|
### Running the Web API
|
|
|
|
```bash
|
|
# Run with poetry
|
|
poetry run fastapi run myice/webapi.py --host 127.0.0.1
|
|
|
|
# Run with uv (alternative)
|
|
uv run fastapi run myice/webapi.py --host 127.0.0.1
|
|
```
|
|
|
|
## Code Style Guidelines
|
|
|
|
### Imports
|
|
|
|
- Standard library imports first, then third-party, then local imports
|
|
- Use explicit imports rather than wildcard imports
|
|
- Group imports logically with blank lines between groups
|
|
|
|
### Formatting
|
|
|
|
- Use ruff-format for automatic formatting
|
|
- Follow PEP 8 style guide
|
|
- Maximum line length: 88 characters (default ruff setting)
|
|
- Use 4 spaces for indentation
|
|
|
|
### Types
|
|
|
|
- Use type hints for function parameters and return values
|
|
- Prefer built-in types (str, int, list, dict) over typing aliases when possible
|
|
- Use typing.Annotated for Typer command options
|
|
|
|
### Naming Conventions
|
|
|
|
- Variables and functions: snake_case
|
|
- Classes: PascalCase
|
|
- Constants: UPPER_SNAKE_CASE
|
|
- Private members: prefixed with underscore (_private)
|
|
|
|
### Error Handling
|
|
|
|
- Use try/except blocks for expected exceptions
|
|
- Raise appropriate HTTPException for API errors
|
|
- Include descriptive error messages
|
|
- Use sys.exit(1) for command-line tool errors
|
|
|
|
### Frameworks and Libraries
|
|
|
|
- Typer for CLI interface
|
|
- FastAPI for web API
|
|
- requests for HTTP requests
|
|
- pypdf for PDF processing
|
|
- Use rich for enhanced console output
|
|
- Custom rl_ai_tools package for AI functionalities
|
|
|
|
### Git Commit Messages
|
|
|
|
- Use conventional commits format
|
|
- Never mention Claude in commit messages
|
|
- Be descriptive but concise
|
|
- Use present tense ("add feature" not "added feature")
|
|
|
|
### Additional Rules
|
|
|
|
- Always use ddg-mcp to perform Web Search functionality
|
|
- Follow the existing code patterns in myice/myice.py and myice/webapi.py
|
|
- Maintain backward compatibility when modifying existing APIs
|
|
- Document new features in README.md
|
|
- Always run ruff format and ruff check after editing a python file
|
|
- Use conventional commit messages
|
|
- When fixing JSON parsing issues, follow the pattern established in
|
|
sanitize_json_response function
|