project-notes

name	project-notes
description	Persistent project knowledge base — decisions, context, conventions

Project Notes

Maintain a persistent knowledge base about the project. Claude reads this at the start of relevant tasks to have context without you re-explaining.

When to use

• "Remember that we use Postgres, not MySQL"
• "What do we know about the auth system?"
• "Add this to project notes"
• "What conventions do we follow?"
• When starting work on a project area you haven't touched in a while

Paths

What	Path
Notes directory	$PROJECT_ROOT/notes/
Architecture notes	$PROJECT_ROOT/notes/architecture.md
Conventions	$PROJECT_ROOT/notes/conventions.md
Decisions log	$PROJECT_ROOT/notes/decisions.md

How to execute

Reading notes

# List all notes
ls $PROJECT_ROOT/notes/

# Read specific topic
cat $PROJECT_ROOT/notes/architecture.md

Adding a note

Append to the appropriate file, or create a new topic file:

## [Topic] (YYYY-MM-DD)

**Decision:** [What was decided]
**Context:** [Why this decision was made]
**Alternatives considered:** [What else was considered]

Note categories

File	What goes here
architecture.md	System design, service boundaries, data flow
conventions.md	Naming, file structure, coding standards
decisions.md	ADRs — why we chose X over Y
integrations.md	External services, API keys location, endpoints
troubleshooting.md	Known issues and their fixes

Examples

Adding a decision

## Use Redis for caching (2024-03-15)

**Decision:** Use Redis instead of in-memory caching
**Context:** App runs on multiple instances, need shared cache
**Alternatives:** Memcached (less features), in-memory (no sharing)

Adding a convention

## API Response Format

All API endpoints return:
\```json
{
  "data": {...},
  "error": null,
  "meta": {"timestamp": "...", "request_id": "..."}
}
\```

Tips

• Keep notes concise — bullet points over paragraphs
• Include dates — context changes over time
• Link to code — src/auth/middleware.ts:45 is better than "the auth middleware"
• Delete outdated notes — stale context is worse than no context

Related skills

• daily-summary — uses project notes for context