From 82c2f701823e19e375a8c854181a763a96620234 Mon Sep 17 00:00:00 2001 From: Peter Stone Date: Sat, 7 Feb 2026 21:21:53 -1000 Subject: Update project docs: fix stale references, add missing sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CLAUDE.md: fix data sources, add debugging/deploy sections, test checklist - DESIGN.md: update directory tree, fix h.templates→h.renderer, add endpoints/env vars - Role files: fix Go version to 1.24, update tool names to Edit/Read/Glob - scripts/logs: fix CRLF line endings for WSL compatibility Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-) (limited to 'CLAUDE.md') diff --git a/CLAUDE.md b/CLAUDE.md index 9bf34fd..b62f21e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,8 +1,8 @@ # Claude Code Project Guidelines ## Project Overview -A unified web dashboard aggregating Trello (PRIMARY), Todoist, Obsidian, and PlanToEat. -**Stack:** Go backend + HTMX + Tailwind CSS + SQLite. +A unified web dashboard aggregating Trello, Todoist, PlanToEat, Google Calendar, and Google Tasks. +**Stack:** Go 1.24 + chi router + HTMX + Tailwind CSS + SQLite. ## Key Documents (Read These First) @@ -12,22 +12,14 @@ A unified web dashboard aggregating Trello (PRIMARY), Todoist, Obsidian, and Pla | `SESSION_STATE.md` | Current task state, next steps | Start of every session | | `docs/adr/*.md` | Architecture Decision Records | Before implementing features in that area | -### Multi-Agent Workflow +### Multi-Agent Workflow (Optional) -This project uses a three-role development workflow. **Read your role definition before starting work:** - -| Role | Definition File | Responsibilities | -|------|-----------------|------------------| -| Architect | `ARCHITECT_ROLE.md` | Plans, documents, creates ADRs. Does NOT edit code. | -| Implementor | `IMPLEMENTOR_ROLE.md` | Executes plans, writes code, runs tests. | -| Reviewer | `REVIEWER_ROLE.md` | Reviews code quality and tests. Does NOT edit code. | - -**Handoff docs:** `instructions.md` (Architect → Implementor), `review_feedback.md` (Reviewer → Implementor) +Role definitions exist for a three-agent pipeline (`ARCHITECT_ROLE.md`, `IMPLEMENTOR_ROLE.md`, `REVIEWER_ROLE.md`) but the **primary workflow is single-agent** — reading CLAUDE.md + DESIGN.md directly. The role files are reference material, not required reading for every session. ## Efficiency & Token Management -- **Context Minimization:** Do not read entire files if `grep`, `sed`, or `ls` can answer a question. +- **Context Minimization:** Use Grep/Glob with offset/limit rather than reading entire files when a targeted search suffices. - **Surgical Edits:** Perform small, targeted file edits. Avoid rewriting entire files for single changes. -- **Dependency Awareness:** Use `go test`, `go build`, and `lint` to verify state rather than asking the agent to "think" through logic. +- **Dependency Awareness:** Use `go test`, `go build` to verify state rather than reasoning through logic. - **Proactive Checkpointing:** Treat every 3-4 turns as a potential session end. Update `SESSION_STATE.md` frequently. ## Workflow: TDD — ALWAYS Write Tests First @@ -48,6 +40,17 @@ This project uses a three-role development workflow. **Read your role definition - **Run:** `go run cmd/dashboard/main.go` - **Test:** `go test ./...` - **Build:** `go build -o dashboard cmd/dashboard/main.go` +- **Deploy:** `bash deploy.sh` (builds with ldflags, pushes, restarts via SSH) + +## Debugging +- **Production logs:** `bash scripts/logs` — fetches journalctl from production via SSH + - `bash scripts/logs -n 100` last N lines + - `bash scripts/logs -f` follow + - `bash scripts/logs --since "1 hour ago"` + - Pipe through `grep` to filter: `bash scripts/logs -n 500 2>&1 | grep -i error` +- **View bugs:** `bash scripts/bugs` — lists open bugs from production database +- **Resolve bug:** `bash scripts/resolve-bug ` — marks a bug as resolved +- **Always check production logs first** when debugging reported issues ## State Management - **SESSION_STATE.md:** The source of truth for resuming work. Must include: @@ -68,6 +71,12 @@ This project uses a three-role development workflow. **Read your role definition - Prioritize terminal-based verification over manual code review. - **Patterns:** See `DESIGN.md` → Development Guide for handler/template patterns. +## Test Quality Checklist +When writing or reviewing tests, verify: +- **Effective:** Assertions match test name. Test would fail if code was broken. +- **Clear:** Arrange-Act-Assert structure. Descriptive names like `TestHandler_MissingField_Returns400`. +- **Complete:** Happy path + error cases + edge cases. Bug fixes include regression tests. + ## Documentation - **ADR-first:** Capture architectural decisions in `docs/adr/*.md`, not one-off design docs. - **Update DESIGN.md** for new features, endpoints, or schema changes. -- cgit v1.2.3