CLAUDE.md

 1# CLAUDE.md
 2
 3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 4
 5## Project
 6
 7**second-brain** — a Python CLI for capturing and organizing quick notes. Built with Click, managed with `uv`.
 8
 9## Commands
10
11~~~
12# Install dependencies
13uv sync
14
15# Run the CLI
16uv run second_brain new "My note title"
17uv run second_brain list
18uv run second_brain show 1
19
20# Tests
21uv run pytest                                    # all tests
22uv run pytest tests/test_notes.py                # single file
23uv run pytest tests/test_notes.py::test_slugify  # single test
24uv run pytest --cov                              # with coverage (80% threshold)
25
26# Lint & format
27uv run ruff check .
28uv run ruff format .
29
30# Docs
31uv run mkdocs build
32uv run python scripts/serve_docs.py
33~~~
34
35## Architecture
36
37~~~
38CLI (cli.py) → Business Logic (notes.py)
39                    ↕
40              Logging (app.py)
41~~~
42
43- **`cli.py`** — Click command group (`new`, `list`, `show`). Reads `SECOND_BRAIN_DIR` env var (default `~/second_brain/`). Delegates all note operations to `notes.py`.
44- **`notes.py`** — Pure business logic: `slugify()`, `build_note_path()` (with collision detection via `-1`, `-2` suffixes), `create_note()` (writes markdown files with heading + ISO timestamp).
45- **`app.py`** — Loguru-based logging config with dual handlers (stderr compact format + file rotation at 50KB).
46- **`__main__.py`** — Module entry point, imports `cli()`.
47
48## Testing
49
50- pytest with `importlib` import mode and strict markers/config
51- `conftest.py` provides `tmp_note_dir` fixture and auto-use `LOG_FILE` fixture
52- `pytest-env` loads `.env.test` (sets `LOG_LEVEL=DEBUG`)
53- Coverage enforced at 80% via `fail_under` in pyproject.toml
54
55## Environment Variables
56
57| Variable | Default | Purpose |
58|---|---|---|
59| `SECOND_BRAIN_DIR` | `~/second_brain/` | Note storage directory |
60| `LOG_LEVEL` | `INFO` | Console log level |
61| `LOG_FILE` | `app.log` | Log file path |
62
63## Conventions
64
65- Commits follow conventional commits (`feat:`, `fix:`, `docs:`, `test:`)
66- Ruff config: line length 88, Python 3.13 target, double quotes, rules E/F/B/I/UP (E501 ignored)

 1## Commands
 2
 3- Dev mode: `uv run --env-file .env second_brain`
 4- Tests: `uv run pytest` 
 5- Docs: `uv run mkdocs build`
 6
 7## Workflow
 8
 9- Always write tests first when implementing features or fixing bugs (TDD).
10- Before committing, ensure docs and `README.md` are updated.
11- When creating new pages in `docs/`, also add them to the nav: section in `mkdocs.yml`.
12- Always check log files when debugging.
13
14## Notes
15
16- pytest-env auto-loads `.env.test` — don't set `LOG_LEVEL` manually in tests.
17- Google-style docstrings (used by `mkdocstrings` for API docs).
18- Docs server logs: `mkdocs.log` (written by `scripts/serve_docs.py`). Check when debugging docs issues.
19- Never start long-running servers (e.g., `serve_docs.py`, `mkdocs serve`). Use `uv run mkdocs build` to verify docs compile.