Skip to content

project-context.md

Latest commit

 

History

History
549 lines (403 loc) · 21.7 KB

project-context.md

File metadata and controls

549 lines (403 loc) · 21.7 KB
name project-context
description White-label project context skill template. Gives an AI agent immediate, structured understanding of your codebase, architecture, and ways of working. Fork this and fill in your own project details.

[Project Name] -- Full Project Context

When to use this skill: Read this at the start of any new conversation involving [Project Name] development. It replaces the need to re-explore the codebase from scratch.

Rules of Engagement -- Read Before Acting

This skill provides context. It does NOT grant permission to modify code.

The developer drives all decisions on this project. Follow these rules strictly:

  1. Requirements come from the developer. Do not infer, assume, or invent requirements. If the developer's request is ambiguous, ask clarifying questions before proposing anything.

  2. Propose before modifying. Before writing or editing any file, present your plan: what you intend to change, which files are affected, and why. Wait for explicit developer approval before proceeding.

  3. Never modify design decisions autonomously. [Describe your project's protected design territory here -- e.g. game balance values, API contracts, database schemas, business logic rules, pricing, user-facing copy. These are decisions that belong to the developer, not the agent.]

  4. Scope your work tightly. Only touch files directly relevant to the current task. Do not opportunistically refactor, rename, or "improve" code in files outside the agreed scope, even if you spot issues. Flag them for the developer instead.

  5. Preserve existing comments and intent. When editing code, maintain all developer-authored comments explaining reasoning or design choices. Do not remove or rewrite them unless the developer specifically asks.

  6. Confirm before running destructive commands. Do not run commands that delete files, reset state, overwrite data, or install dependencies without developer approval.

  7. Use established patterns. This skill documents how the codebase works. When implementing changes, follow the conventions described here. Do not introduce new architectural patterns, libraries, or paradigms without discussion.

  8. [Add any repo/deployment rules here.] [e.g. "Development happens in the private workspace. Production code is pushed to the public repo ONLY via the /deploy workflow. Never manually copy source files to the public repo."]

In short: Read -> Understand -> Discuss -> Plan -> Get Approval -> Implement. This is a collaborative workflow, not an autonomous one.

1. What Is [Project Name]?

[Project Name] is a [type of project] built in [technology stack]. Run locally via [dev command] which serves at [local URL].

Core purpose / user flow: [Describe the primary thing the project does and how users interact with it.]

Authoritative documentation: See [path to main docs, e.g. README.md] in the project root. This is the single source of truth for [what it covers]. If you need to know [key details] -- read this file first.

2. Project Structure

[project-root]/
├── src/                       # Application source code
│   ├── index.[ext]            # Entry point
│   ├── config.[ext]           # Constants, enums, feature flags
│   ├── [module].[ext]         # [Brief description]
│   ├── [module].[ext]         # [Brief description]
│   ├── [subsystem]/           # [Subsystem name] sub-modules
│   │   ├── [file].[ext]       # [Brief description]
│   │   └── [file].[ext]       # [Brief description]
│   └── ...
├── tests/                     # Test suite
│   ├── [test-file]            # [What it tests]
│   └── helpers/               # Test utilities
├── scripts/                   # Build, deploy, and utility scripts
│   ├── build.[ext]            # [What it does]
│   └── deploy.[ext]           # [What it does]
├── public/                    # Static assets (if applicable)
├── docs/                      # Documentation (if separate from README)
├── .agents/                   # AI agent workflows and skills
│   ├── workflows/             # Slash-command workflow definitions
│   └── skills/                # Context skills (including this file)
├── [config files]             # package.json, tsconfig, etc.
├── README.md                  # [What it covers]
├── CHANGELOG.md               # Version history
└── LICENSE                    # License type

3. Architecture Overview

Module Pattern

[Describe your module system. Example: "All files use ES modules with explicit import/export. There is no global namespace. The entry point is src/main.js, loaded via <script type="module"> in index.html."]

Build Pipeline

[Describe your build process. Example: "Vite handles HMR in dev. Production builds to dist/ via npm run build. Output is a single bundled JS file + hashed assets."]

External Dependencies

  • [Library] -- [Purpose] ([how loaded: npm / CDN / vendored])
  • [Library] -- [Purpose] ([how loaded])
  • ...

4. Key Systems In Depth

4.1 [Core System Name] ([file path])

[One sentence: what this system does and why it matters.]

Key properties / API:

Property / Method Type / Signature Purpose
[name] [type] [What it does]
[name] [type] [What it does]

Critical pattern: [Document the most important invariant. Example: "State mutations automatically trigger a UI re-render via a dirty flag. You do NOT need to manually trigger renders after state changes."]

4.2 [Second System Name] ([file path])

[Repeat the same structure for each major system.]

4.3 [Third System Name] -- and so on

5. Coding Standards

ID Rule Key Point
CODE_01 [Rule name] [One-line summary]
CODE_02 [Rule name] [One-line summary]
CODE_03 [Rule name] [One-line summary]
... ... ...

Architectural Principles

ID Principle
ARCH_01 [e.g. "State and DOM are fully decoupled"]
ARCH_02 [e.g. "CSS handles aesthetics; JS handles logic only"]
ARCH_03 [e.g. "Single source of truth for all application state"]
... ...

6. Key Patterns & Conventions

[Pattern Name]

[2-3 sentence explanation of what this pattern is and why you use it.]

// Example code showing the pattern

[Pattern Name]

[Repeat for each important pattern.]

7. Testing

Framework: [e.g. Playwright, Jest, Vitest, pytest]

Running tests:

[command to run all tests]
[command to run tests in watch/headed mode]
[command to run a specific test file]

Test files: [Describe where tests live and naming conventions.]

Helpers: [Describe any shared test utilities, fixtures, or harness modules.]

8. Deployment & Version Control

[Describe your repository structure, branching strategy, and deployment pipeline.]

Deployment Pipeline

[Step-by-step: what happens when code goes to production.]

Guardrails

  • Never [e.g. "push directly to main without the deploy workflow"]
  • Never [e.g. "commit source files to the public repo"]
  • ...

9. Existing Workflows & Skills

Command File Purpose
/[workflow] [path] [What it does]
/[workflow] [path] [What it does]
... ... ...

10. Quick Reference

Metric / Value Value Config Location
[Key setting] [Value] [where it lives]
[Key setting] [Value] [where it lives]
... ... ...

11. Common Development Tasks

[Task Name, e.g. "Adding a New API Endpoint"]

  1. [Step one, including which file to modify]
  2. [Step two]
  3. [Step three]
  4. ...

[Task Name, e.g. "Adding a New Component"]

  1. [Step one]
  2. [Step two]
  3. ...

[Task Name, e.g. "Modifying Configuration Values"]

  1. [Step one]
  2. [Step two]
  3. ...

12. Important Gotchas

  1. [Short title]. [Explanation of the gotcha and what to do about it.]

  2. [Short title]. [Explanation.]

  3. [Short title]. [Explanation.]

13. Skill Maintenance -- Keeping This Document Alive

This skill is a living document. Its value grows with the project, but only if it is reviewed and updated regularly.

When to Trigger a Review

Run a skill review after any of the following:

  • A major feature is completed (new system, new module, significant refactor)
  • A new architectural pattern is introduced (new module decomposition, new data flow)
  • A painful debugging session reveals a non-obvious gotcha
  • Files are renamed, moved, or deleted (file tree goes stale)
  • A new workflow or skill is added (Section 9 needs updating)
  • Configuration values change (Quick Reference table goes stale)
  • Roughly every 4-6 sessions, even if nothing dramatic changed -- small drift accumulates

How to Run a Review

Ask the agent:

"Review the project-context skill against the current state of the codebase. Propose updates for my approval before writing anything."

The agent should then work through the following checklist and propose changes section by section. The developer approves each change before it is written.

Review Checklist

# Check Section(s) Affected
1 File tree accuracy. Are all directories and key files still correctly listed? Have any been added, renamed, or removed? Section 2
2 Architecture changes. Has the module pattern, build pipeline, or dependency list changed? Any new external libraries? Section 3
3 New systems. Were any new systems introduced that deserve a deep-dive subsection? Section 4
4 Changed systems. Have any documented systems gained new methods, properties, or changed behaviour? Section 4
5 New coding standards. Were any new conventions established during recent work that should be codified? Section 5
6 New patterns. Were any new recurring patterns introduced (e.g. a new composition pattern, a new error handling approach)? Section 6
7 Test changes. Have test files, helpers, or running instructions changed? Section 7
8 Quick Reference drift. Have any key values, thresholds, or config locations changed? Any new ones worth adding? Section 10
9 New common tasks. Did the recent work establish a repeatable recipe that should be documented for next time? Section 11
10 New gotchas. Did any non-obvious behaviours, traps, or "I wasted time on this" moments surface? Section 12

After the Review

Once updates are approved and written, add an entry to the maintenance log below. This creates a lightweight history of how the skill has evolved, and helps you see at a glance when it was last reviewed.

Maintenance Log

Date Trigger Changes Made
[YYYY-MM-DD] [Initial creation] [Populated all sections from scratch]