Project Notes

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: anthroos
• Source: anthroos/claude-code-orchestrator
• License: MIT

Install and usage instructions live in the source repository linked above.