Coding guidelines for Copilot

Project Structure

Keep modules small (single responsibility).
Place reusable utilities in a
```
utils
```
or
```
lib
```
package with
```
__all__
```
defined.
Expose public API via package
```
__init__.py
```
; avoid star imports elsewhere.

Type Hints & Static Analysis

Use
```
from __future__ import annotations
```
at top of new modules when forward refs help.
Prefer
```
TypedDict
```
,
```
Protocol
```
,
```
NewType
```
, and
```
Literal
```
for precision.
Run
```
mypy
```
(strict mode) in CI; fix or silence with targeted
```
# type: ignore[code]
```
.

Async & Concurrency

For CPU-bound tasks, use
```
concurrent.futures.ProcessPoolExecutor
```
.
Wrap blocking calls in
```
asyncio.to_thread
```
.
Always cancel pending tasks on shutdown; use
```
asyncio.TaskGroup
```
where possible.

Error Handling

Raise domain-specific exceptions; create a
```
exceptions.py
```
module.
Avoid bare
```
except
```
; catch specific exceptions.
Log and re-raise only when adding context.

Logging

Use the standard
```
logging
```
library; configure in a single
```
logging_config.py
```
.
Structure logs (e.g.,
```
extra
```
dict) for observability.
Do not log secrets or PII.

Configuration

Load config via
```
pydantic
```
settings or
```
dataclasses
```
.
Read environment variables in one place; inject config, avoid global state.

Dependency Management

Pin direct dependencies in
```
pyproject.toml
```
; use constraints for transitive locking.
Keep runtime deps minimal; move tooling to
```
dev
```
optional group.

Testing

Aim for high coverage of critical paths; value meaningful assertions over %.
Use factories/builders for complex objects.
Mark slow or integration tests (
```
@pytest.mark.slow
```
) and isolate external services (use
```
pytest-asyncio
```
for async tests).
Property-based tests (
```
hypothesis
```
) for pure logic.

Documentation

Provide a concise module docstring summarizing purpose and main abstractions.
Use docstrings for public functions/classes only; keep private helpers self-explanatory.
Maintain a
```
CHANGELOG.md
```
(Keep a Changelog format) and semantic versioning.

Performance

Optimize only after profiling (
```
cProfile
```
,
```
pyinstrument
```
).
Prefer clarity; micro-optimizations require comments with rationale.
Cache expensive pure functions with
```
functools.lru_cache
```
.

Security

Validate all external input.
Use parameterized queries (never string-concatenate SQL).
Regularly run dependency vulnerability scans.

Style Consistency

Let
```
black
```
and
```
ruff
```
handle formatting & lint rules; avoid manual bikeshedding.
Keep line length default unless strong reason otherwise.

Data Models

For structured data exchange, prefer
```
pydantic
```
models or
```
dataclasses
```
.
Avoid leaking internal model shapes across boundaries; translate at edges.

Serialization

Use explicit include/exclude lists; never rely on
```
__dict__
```
blindly.
For timestamps, use timezone-aware UTC
```
datetime
```
.

CLI & Scripts

Use

argparse

typer

for CLIs; expose a

main()

guarded by

if __name__ == "__main__":

Return exit codes instead of
```
sys.exit
```
deep in logic.

Code Review Checklist

Clear responsibilities?
Adequate tests (positive, negative, edge)?
Proper error handling and logging?
No secrets or credentials?
Types precise and pass static checks?
Readable naming & no dead code?

Git & Commits

Use conventional commit prefixes (
```
feat:
```
,
```
fix:
```
,
```
chore:
```
,
```
docs:
```
).
Keep commits focused; avoid mixing refactors with behavior changes.

Copilot Prompting Hints

Start files with a short comment explaining intent to guide suggestions.
Write function signature + docstring skeleton first; let completions fill body.
When suggestions are off-target, add a clarifying comment about algorithm/constraints.

Example Docstring Template

""" Summary line.

Args: param_name: Short description.

Returns: Description of return value.

Raises: SpecificError: Condition description. """

Anti-Patterns to Avoid

Large functions (> ~40 lines) without refactoring.
Hidden mutations of shared state.
Swallowing exceptions silently.
Re-implementing standard library utilities.

Continuous Integration

Pipeline stages: lint -> type check -> test -> build -> security scan.
Fail fast on lint/type errors before running the full test matrix.

Deployment

Ensure deterministic builds (hash seed, pinned dependencies).
Provide health check endpoints for services.
Surface version/build info at runtime for traceability.

Adhere to these practices to maintain clarity, safety, and long-term maintainability.