├── README.md
├── Setting Up Cursor for WordPress Projects.md
├── Guide for Effective Collaboration with Cursor.md
└── Claude Code MCP Guide.md
/README.md:
--------------------------------------------------------------------------------
1 | # Manual for AI Development Collaboration
2 |
3 | ## Table of Contents
4 |
5 | 1. [Introduction](#introduction)
6 | 2. [Project Setup and Structure](#project-setup-and-structure)
7 | - [Starting a New Project](#starting-a-new-project)
8 | - [Resuming an Existing Project](#resuming-an-existing-project)
9 | - [Project Manifests](#project-manifests)
10 | 3. [Effective Communication Patterns](#effective-communication-patterns)
11 | - [Setting Clear Objectives](#setting-clear-objectives)
12 | - [Command Pattern for Clear Instructions](#command-pattern-for-clear-instructions)
13 | - [Managing Complex Requirements](#managing-complex-requirements)
14 | 4. [Session Management](#session-management)
15 | - [Starting a Development Session](#starting-a-development-session)
16 | - [Ending a Development Session](#ending-a-development-session)
17 | - [Handling Context Switches](#handling-context-switches)
18 | 5. [Strategic Checkpoints](#strategic-checkpoints)
19 | - [When to Create Checkpoints](#when-to-create-checkpoints)
20 | - [Communication Patterns for Checkpoints](#communication-patterns-for-checkpoints)
21 | - [Tips for Smooth Collaboration](#tips-for-smooth-collaboration)
22 | 6. [Context Persistence](#context-persistence)
23 | - [The Context Persistence Problem](#the-context-persistence-problem)
24 | - [Project Context Management System](#project-context-management-system)
25 | - [Context Restoration Process](#context-restoration-process)
26 | - [Code Signposts](#code-signposts)
27 | 7. [Troubleshooting](#troubleshooting)
28 | - [When the AI Is Missing Context](#when-the-ai-is-missing-context)
29 | - [When Implementation Is Off-Track](#when-implementation-is-off-track)
30 | - [Handling Workflow Disruptions](#handling-workflow-disruptions)
31 | 8. [Testing and Quality Assurance](#testing-and-quality-assurance)
32 | - [Requesting Testing Instructions](#requesting-testing-instructions)
33 | - [Providing Test Results](#providing-test-results)
34 | 9. [Templates Library](#templates-library)
35 | - [Standard Project Manifest](#standard-project-manifest)
36 | - [Minimal Project Manifest](#minimal-project-manifest)
37 | - [Quick Session Resume](#quick-session-resume)
38 | - [Session Summary](#session-summary)
39 | - [Code Context](#code-context)
40 | 10. [Example Workflow](#example-workflow)
41 |
42 | ## Introduction
43 |
44 | Working with AI development tools like Claude Code presents unique challenges and opportunities. Unlike human developers, AI tools may not naturally recognize when to pause for feedback and can lose context between sessions. This manual provides a structured approach to maximize the effectiveness of your AI development partnership.
45 |
46 | The primary challenges addressed in this guide include:
47 |
48 | 1. **Continuous Flow**: AI can get into a "flow state" and continue generating code without natural stopping points. Unlike human developers who recognize when to pause for feedback, AI tools need explicit guidance on when to stop for review.
49 |
50 | 2. **Context Loss**: Sessions get interrupted, chats close accidentally, or context windows fill up, resulting in the AI losing track of what has been built so far. This creates discontinuity in the development process.
51 |
52 | This manual offers practical strategies to establish a collaborative rhythm with AI developer tools without disrupting their productive flow, while maintaining context across sessions.
53 |
54 | ## Project Setup and Structure
55 |
56 | ### Starting a New Project
57 |
58 | When starting a new project with an AI counterpart, begin with:
59 |
60 | ```
61 | I'm starting a new project called [PROJECT_NAME]. It's [BRIEF_DESCRIPTION].
62 |
63 | Here's our project manifest to track progress:
64 |
65 | [PASTE STANDARD PROJECT MANIFEST]
66 |
67 | Let's begin by [SPECIFIC FIRST TASK]. Please acknowledge this context before we start.
68 | ```
69 |
70 | ### Resuming an Existing Project
71 |
72 | When resuming work after a break or context loss:
73 |
74 | ```
75 | We're continuing work on [PROJECT_NAME]. Here's our current project manifest:
76 |
77 | [PASTE FILLED-IN PROJECT MANIFEST]
78 |
79 | Here's a quick summary of where we left off:
80 |
81 | [PASTE FILLED-IN QUICK SESSION RESUME]
82 |
83 | Please review this information and let me know if you have any questions before we continue.
84 | ```
85 |
86 | ### Project Manifests
87 |
88 | Project manifests serve as a central reference point for maintaining context across development sessions. Two types of manifests are provided based on project complexity:
89 |
90 | 1. **Standard Project Manifest**: For comprehensive projects with multiple components
91 | 2. **Minimal Project Manifest**: For smaller projects or focused development sessions
92 |
93 | Use these manifests to:
94 | - Record architectural decisions
95 | - Track progress on different components
96 | - Document current status and next steps
97 | - Maintain important context across sessions
98 |
99 | ## Effective Communication Patterns
100 |
101 | ### Setting Clear Objectives
102 |
103 | Begin each session with clear objectives:
104 |
105 | ```
106 | Today, we're focusing on [SPECIFIC_GOAL]. Our success criteria are:
107 | 1. [CRITERION_1]
108 | 2. [CRITERION_2]
109 | 3. [CRITERION_3]
110 |
111 | Let's tackle this step by step.
112 | ```
113 |
114 | ### Command Pattern for Clear Instructions
115 |
116 | Use a consistent command pattern to signal your intentions:
117 |
118 | - `[ANALYZE]`: Request analysis of code or a problem
119 | - `[IMPLEMENT]`: Request implementation of a feature
120 | - `[REVIEW]`: Request code review
121 | - `[DEBUG]`: Request help with debugging
122 | - `[REFACTOR]`: Request code improvement
123 | - `[DOCUMENT]`: Request documentation
124 | - `[CONTINUE]`: Signal to continue previous work
125 |
126 | Example:
127 | ```
128 | [IMPLEMENT] Create a user authentication system with the following requirements:
129 | - Email/password login
130 | - Social login (Google, Facebook)
131 | - Multi-factor authentication
132 | - Password reset flow
133 | ```
134 |
135 | ### Managing Complex Requirements
136 |
137 | For complex features, provide specifications in a structured format:
138 |
139 | ```
140 | We need to implement [FEATURE]. Here are the specifications:
141 |
142 | Requirements:
143 | - [REQUIREMENT_1]
144 | - [REQUIREMENT_2]
145 | - [REQUIREMENT_3]
146 |
147 | Technical constraints:
148 | - [CONSTRAINT_1]
149 | - [CONSTRAINT_2]
150 |
151 | Acceptance criteria:
152 | - [CRITERION_1]
153 | - [CRITERION_2]
154 | - [CRITERION_3]
155 |
156 | Please confirm your understanding of these requirements before proceeding.
157 | ```
158 |
159 | ## Session Management
160 |
161 | ### Starting a Development Session
162 |
163 | ```
164 | Let's begin today's development session. Here's our agenda:
165 | 1. Review what we accomplished last time ([BRIEF_SUMMARY])
166 | 2. Continue implementing [CURRENT_FEATURE]
167 | 3. Test [COMPONENT(S)_TO_TEST]
168 |
169 | We'll work on each item in sequence, pausing between them for my review.
170 | ```
171 |
172 | ### Ending a Development Session
173 |
174 | ```
175 | Let's wrap up this session. Please provide a session summary using this template:
176 |
177 | [PASTE SESSION SUMMARY TEMPLATE]
178 |
179 | We'll use this to continue our work in the next session.
180 | ```
181 |
182 | ### Handling Context Switches
183 |
184 | When you need to switch to a different component or feature:
185 |
186 | ```
187 | We need to switch focus to [NEW_COMPONENT/FEATURE]. Here's the relevant context:
188 |
189 | Component: [COMPONENT_NAME]
190 | Status: [CURRENT_STATUS]
191 | Files involved:
192 | - [FILE_PATH_1]: [BRIEF_DESCRIPTION]
193 | - [FILE_PATH_2]: [BRIEF_DESCRIPTION]
194 |
195 | Let's put our current work on [CURRENT_COMPONENT] on hold and address this new priority.
196 | ```
197 |
198 | ## Strategic Checkpoints
199 |
200 | Establish checkpoints to ensure collaborative development without disrupting productive flow.
201 |
202 | ### Setting Up Expectations
203 |
204 | Start your development session with clear checkpoint expectations:
205 |
206 | ```
207 | "As you develop this feature, please pause at logical completion points and explicitly ask me if I want to test what you've built so far before continuing."
208 | ```
209 |
210 | For more complex projects, establish a step-by-step process:
211 |
212 | ```
213 | "Please develop this feature in stages:
214 | 1. First, design the component and wait for my approval
215 | 2. Implement the core functionality and pause for testing
216 | 3. Only after my feedback, continue to the next phase"
217 | ```
218 |
219 | ### When to Create Checkpoints
220 |
221 | Establish checkpoints after:
222 |
223 | 1. **Architecture design** – Before any code is written
224 | 2. **Core functionality** – When basic features are implemented
225 | 3. **Database interactions** – After schema design or query implementation
226 | 4. **API endpoints** – When endpoints are defined but before full integration
227 | 5. **UI components** – After key interface elements are created
228 | 6. **Integration points** – When connecting different system components
229 |
230 | ### Communication Patterns for Checkpoints
231 |
232 | Teach your AI to use these signaling phrases:
233 |
234 | - **CHECKPOINT**: "I've completed [specific component]. Would you like to test this before I continue?"
235 | - **TESTING OPPORTUNITY**: "This is a good moment to verify the implementation."
236 | - **MILESTONE REACHED**: "[Feature X] is ready for user testing. Here's how to test it: [instructions]"
237 |
238 | ### Tips for Smooth Collaboration
239 |
240 | - **Be specific about testing requirements** – "When you reach a testable point for the user authentication system, include instructions for testing both successful and failed login attempts."
241 |
242 | - **Set time or complexity boundaries** – "If you've been developing for more than 10 minutes without a checkpoint, please pause and check in."
243 |
244 | - **Provide feedback on checkpoint frequency** – "You're stopping too often/not often enough. Let's adjust to pause only after completing [specific scope]."
245 |
246 | ## Context Persistence
247 |
248 | ### The Context Persistence Problem
249 |
250 | AI development tools have limited context windows and don't maintain state between sessions. When a chat closes or context is lost, the AI loses track of:
251 | - Project structure and files
252 | - Design decisions made
253 | - Implementation details
254 | - Current development stage
255 |
256 | ### Project Context Management System
257 |
258 | Implement a simple context management system with these components:
259 |
260 | #### 1. Project Manifest File
261 |
262 | Create a `project-manifest.md` file that contains:
263 |
264 | ```markdown
265 | # Project Manifest: [Project Name]
266 |
267 | ## Project Overview
268 | [Brief description of the project]
269 |
270 | ## Architecture
271 | [Key architectural decisions]
272 |
273 | ## Current Status
274 | - Last updated: [Date/Time]
275 | - Current milestone: [e.g., "Implementing user authentication"]
276 | - Current stage: [e.g., "70% complete"]
277 |
278 | ## Components
279 | - [Component 1]: [Status] - [Brief description]
280 | - [Component 2]: [Status] - [Brief description]
281 | ...
282 |
283 | ## Next Steps
284 | - [Immediate next tasks]
285 | - [Planned features]
286 |
287 | ## Testing Notes
288 | - [Testing instructions]
289 | - [Known issues]
290 |
291 | ## Configuration
292 | - [Environment setup]
293 | - [Dependencies]
294 | ```
295 |
296 | #### 2. Checkpoint Snapshots
297 |
298 | At each checkpoint:
299 | 1. Save a snapshot of the current project state
300 | 2. Update the manifest file with current status
301 | 3. Export any critical implementation details
302 |
303 | ### Context Restoration Process
304 |
305 | When restarting development:
306 |
307 | 1. Share the project manifest with the AI
308 | 2. Provide the most recent relevant code files
309 | 3. Use this prompt template:
310 |
311 | ```
312 | "We're continuing development on [Project Name]. Here's our project manifest and current status.
313 | The last thing we implemented was [specific feature/component].
314 | Please review the manifest and current code to understand where we left off.
315 | Our next task is to [specific next task].
316 | Please acknowledge your understanding of the current state before proceeding."
317 | ```
318 |
319 | ### Code Signposts
320 |
321 | Use specially formatted comments that help with context resumption:
322 |
323 | ```javascript
324 | // [CONTEXT:START] Authentication System
325 | // Implements JWT-based authentication with refresh tokens
326 | // Current status: Login and registration complete, password reset in progress
327 | // [CONTEXT:END]
328 | ```
329 |
330 | ## Troubleshooting
331 |
332 | ### When the AI Is Missing Context
333 |
334 | If the AI seems to be missing important context:
335 |
336 | ```
337 | I notice you may be missing some key context. Here's what you need to know:
338 |
339 | - [CRITICAL_PIECE_OF_CONTEXT_1]
340 | - [CRITICAL_PIECE_OF_CONTEXT_2]
341 | - [CRITICAL_PIECE_OF_CONTEXT_3]
342 |
343 | Let's refocus on [CURRENT_TASK] with this information in mind.
344 | ```
345 |
346 | ### When Implementation Is Off-Track
347 |
348 | If development is going in the wrong direction:
349 |
350 | ```
351 | I'd like to redirect our approach. The current implementation [ISSUE_WITH_CURRENT_APPROACH].
352 |
353 | Let's adjust by:
354 | 1. [ADJUSTMENT_1]
355 | 2. [ADJUSTMENT_2]
356 | 3. [ADJUSTMENT_3]
357 |
358 | Does this new direction make sense to you?
359 | ```
360 |
361 | ### Handling Workflow Disruptions
362 |
363 | If the AI continues without pausing at appropriate checkpoints:
364 |
365 | 1. Intervene with: "Let's pause here. I'd like to test what we have so far."
366 | 2. Reinforce the checkpoint pattern: "Going forward, please pause after completing each [component type]."
367 | 3. Be specific about what you're testing and why to help the AI learn appropriate stopping points.
368 |
369 | ## Testing and Quality Assurance
370 |
371 | ### Requesting Testing Instructions
372 |
373 | ```
374 | Now that we've implemented [FEATURE], please provide me with testing instructions:
375 |
376 | 1. How should I test the happy path?
377 | 2. What edge cases should I verify?
378 | 3. Are there any potential performance concerns I should look for?
379 | 4. How will I know if the implementation is successful?
380 | ```
381 |
382 | ### Providing Test Results
383 |
384 | ```
385 | I've tested [FEATURE] and here are my findings:
386 |
387 | ✅ Successes:
388 | - [SUCCESS_1]
389 | - [SUCCESS_2]
390 |
391 | ❌ Issues:
392 | - [ISSUE_1]
393 | - [ISSUE_2]
394 |
395 | Let's address these issues before moving on.
396 | ```
397 |
398 | ## Templates Library
399 |
400 | ### Standard Project Manifest
401 |
402 | ```markdown
403 | # Project Manifest: [PROJECT_NAME]
404 |
405 | ## Project Overview
406 | [PROJECT_DESCRIPTION]
407 |
408 | ## Current Status
409 | - **Last Updated**: [DATE]
410 | - **Current Phase**: [PHASE]
411 | - **Progress**: [PROGRESS_PERCENTAGE]%
412 | - **Active Branch**: [BRANCH_NAME]
413 |
414 | ## Key Architecture
415 | - **Frontend**: [FRONTEND_TECH]
416 | - **Backend**: [BACKEND_TECH]
417 | - **Database**: [DATABASE_TECH]
418 | - **Deployment**: [DEPLOYMENT_STRATEGY]
419 |
420 | ## Components/Modules
421 |
422 | ### 1. [COMPONENT_1_NAME]
423 | - **Status**: [STATUS] ([PERCENTAGE]% complete)
424 | - **Description**: [DESCRIPTION]
425 | - **Current Task**: [CURRENT_TASK]
426 | - **Next Task**: [NEXT_TASK]
427 | - **Dependencies**: [DEPENDENCIES]
428 | - **Testing**: [TESTING_APPROACH]
429 | - **Location**: [CODE_LOCATION]
430 |
431 | ### 2. [COMPONENT_2_NAME]
432 | - **Status**: [STATUS] ([PERCENTAGE]% complete)
433 | - **Description**: [DESCRIPTION]
434 | - **Current Task**: [CURRENT_TASK]
435 | - **Next Task**: [NEXT_TASK]
436 | - **Dependencies**: [DEPENDENCIES]
437 | - **Testing**: [TESTING_APPROACH]
438 | - **Location**: [CODE_LOCATION]
439 |
440 | ### 3. [COMPONENT_3_NAME]
441 | - **Status**: [STATUS] ([PERCENTAGE]% complete)
442 | - **Description**: [DESCRIPTION]
443 | - **Current Task**: [CURRENT_TASK]
444 | - **Next Task**: [NEXT_TASK]
445 | - **Dependencies**: [DEPENDENCIES]
446 | - **Testing**: [TESTING_APPROACH]
447 | - **Location**: [CODE_LOCATION]
448 |
449 | ## Immediate Next Steps
450 | 1. [NEXT_STEP_1]
451 | 2. [NEXT_STEP_2]
452 | 3. [NEXT_STEP_3]
453 |
454 | ## Recent Decisions
455 | - [DECISION_1] ([DATE])
456 | - [DECISION_2] ([DATE])
457 | - [DECISION_3] ([DATE])
458 |
459 | ## Known Issues
460 | - [ISSUE_1]
461 | - [ISSUE_2]
462 | - [ISSUE_3]
463 |
464 | ## Environment Setup
465 | - [REQUIREMENT_1]
466 | - [REQUIREMENT_2]
467 | - [REQUIREMENT_3]
468 | - [CONFIGURATION_NOTES]
469 |
470 | ---
471 |
472 | ## Context Restoration Notes
473 | Last session ([DATE]), we [PREVIOUS_WORK]. We left off at [STOPPING_POINT].
474 |
475 | The next task is to [NEXT_TASK_DETAILS].
476 |
477 | Key context for the current task:
478 | - [CONTEXT_1]
479 | - [CONTEXT_2]
480 | - [CONTEXT_3]
481 | ```
482 |
483 | ### Minimal Project Manifest
484 |
485 | ```markdown
486 | # Project Manifest: [PROJECT_NAME]
487 |
488 | ## Project Overview
489 | [PROJECT_DESCRIPTION]
490 |
491 | ## Current Status
492 | - **Last Updated**: [DATE]
493 | - **Current Task**: [CURRENT_TASK]
494 | - **Next Task**: [NEXT_TASK]
495 |
496 | ## Project Structure
497 | - [KEY_COMPONENT_1]: [BRIEF_DESCRIPTION]
498 | - [KEY_COMPONENT_2]: [BRIEF_DESCRIPTION]
499 | - [KEY_COMPONENT_3]: [BRIEF_DESCRIPTION]
500 |
501 | ## Environment Setup
502 | - [KEY_TECHNOLOGY_1]
503 | - [KEY_TECHNOLOGY_2]
504 | - [KEY_TECHNOLOGY_3]
505 |
506 | ## Context Restoration
507 | Last session, we [PREVIOUS_WORK]. We're now working on [CURRENT_FOCUS].
508 |
509 | Key context:
510 | - [CRITICAL_CONTEXT_1]
511 | - [CRITICAL_CONTEXT_2]
512 | ```
513 |
514 | ### Quick Session Resume
515 |
516 | ```markdown
517 | # Quick Session Resume
518 |
519 | ## Project: [PROJECT_NAME]
520 |
521 | I'm continuing our work on [PROJECT_NAME]. We're in the middle of implementing [FEATURE/COMPONENT].
522 |
523 | ## Current State
524 | - We've completed: [COMPLETED_ITEMS]
525 | - We're currently working on: [CURRENT_TASK]
526 | - Our most recent change was: [LAST_CHANGE]
527 |
528 | ## Important Context
529 | - [KEY_FILE_1] contains [RELEVANT_FUNCTIONALITY_1]
530 | - [KEY_FILE_2] depends on [DEPENDENCY_INFORMATION]
531 | - We decided to [RECENT_DECISION] because [REASONING]
532 |
533 | ## Today's Goal
534 | Let's continue by [SPECIFIC_NEXT_TASK]. This involves:
535 | 1. [SUBTASK_1]
536 | 2. [SUBTASK_2]
537 | 3. [SUBTASK_3]
538 |
539 | Please review this context and let me know when you're ready to continue.
540 | ```
541 |
542 | ### Session Summary
543 |
544 | ```markdown
545 | # Session Summary: [DATE]
546 |
547 | ## Project: [PROJECT_NAME]
548 |
549 | ## What Was Accomplished
550 | - [ACCOMPLISHMENT_1]
551 | - [ACCOMPLISHMENT_2]
552 | - [ACCOMPLISHMENT_3]
553 |
554 | ## Code Changes
555 | - [FILE_PATH_1]: [WHAT_CHANGED]
556 | - [FILE_PATH_2]: [WHAT_CHANGED]
557 | - [FILE_PATH_3]: [WHAT_CHANGED]
558 |
559 | ## Decisions Made
560 | - [DECISION_1]
561 | - [DECISION_2]
562 |
563 | ## Issues Encountered
564 | - [ISSUE_1]: [BRIEF_DESCRIPTION]
565 | - [ISSUE_2]: [BRIEF_DESCRIPTION]
566 |
567 | ## Next Steps
568 | - [NEXT_STEP_1]
569 | - [NEXT_STEP_2]
570 | - [NEXT_STEP_3]
571 |
572 | ## Notes for Next Session
573 | [IMPORTANT_CONTEXT_FOR_NEXT_SESSION]
574 | ```
575 |
576 | ### Code Context
577 |
578 | ```javascript
579 | // [CONTEXT:START] [COMPONENT_NAME]
580 | // Purpose: [COMPONENT_PURPOSE]
581 | // Current status: [COMPONENT_STATUS]
582 | // Key dependencies:
583 | // - [DEPENDENCY_1]
584 | // - [DEPENDENCY_2]
585 | // Last modified: [DATE] - [CHANGES_MADE]
586 | // Next planned changes: [PLANNED_CHANGES]
587 | // Known issues:
588 | // - [ISSUE_1]
589 | // - [ISSUE_2]
590 | // [CONTEXT:END]
591 |
592 | // Regular code begins below this line
593 | ```
594 |
595 | ## Example Workflow
596 |
597 | Here's a typical workflow using the templates and strategies in this manual:
598 |
599 | 1. **Start project**
600 | - Create Standard Project Manifest
601 | - Set clear expectations for development flow and checkpoints
602 | - Begin implementation with clear objectives
603 |
604 | 2. **During development**
605 | - Use command pattern for clear instructions
606 | - Establish checkpoints at logical intervals
607 | - Document code using Code Context Template
608 | - Provide feedback on checkpoint frequency
609 |
610 | 3. **End session**
611 | - Create Session Summary
612 | - Update Project Manifest
613 | - Document next steps
614 |
615 | 4. **Resume later**
616 | - Share Project Manifest and relevant code
617 | - Use Quick Session Resume Template
618 | - Confirm AI's understanding before continuing
619 |
620 | 5. **Repeat** until project completion
621 |
622 | By maintaining this structured approach to communication and context management, you'll maximize the effectiveness of your AI development partnership and ensure consistent progress regardless of session interruptions or context limitations.
623 |
--------------------------------------------------------------------------------
/Setting Up Cursor for WordPress Projects.md:
--------------------------------------------------------------------------------
1 | # Setting Up Cursor for WordPress Projects: A Comprehensive Guide
2 |
3 | ## Table of Contents
4 |
5 | 1. [Introduction](#introduction)
6 | 2. [Installing and Configuring Cursor](#installing-and-configuring-cursor)
7 | - [Basic Installation](#basic-installation)
8 | - [WordPress-Specific Configuration](#wordpress-specific-configuration)
9 | 3. [Setting Up Rules for AI](#setting-up-rules-for-ai)
10 | - [Creating a Rules File](#creating-a-rules-file)
11 | - [WordPress-Specific Rules Template](#wordpress-specific-rules-template)
12 | - [Explanation of Rules](#explanation-of-rules)
13 | 4. [Project Structure Organization](#project-structure-organization)
14 | - [WordPress Plugin Structure](#wordpress-plugin-structure)
15 | - [Including Key Files in Context](#including-key-files-in-context)
16 | 5. [Workflow Best Practices](#workflow-best-practices)
17 | - [Plugin Development Workflow](#plugin-development-workflow)
18 | - [Gutenberg Block Development](#gutenberg-block-development)
19 | - [REST API Endpoint Development](#rest-api-endpoint-development)
20 | 6. [Context Management for WordPress](#context-management-for-wordpress)
21 | - [Managing WordPress Core Context](#managing-wordpress-core-context)
22 | - [Theme vs Plugin Context](#theme-vs-plugin-context)
23 | 7. [Prompting Techniques for WordPress Development](#prompting-techniques-for-wordpress-development)
24 | - [Plugin Feature Development](#plugin-feature-development)
25 | - [Debugging WordPress Issues](#debugging-wordpress-issues)
26 | - [Code Optimization and Refactoring](#code-optimization-and-refactoring)
27 | 8. [Advanced Techniques](#advanced-techniques)
28 | - [Working with Multiple Plugins](#working-with-multiple-plugins)
29 | - [Theme Development in Cursor](#theme-development-in-cursor)
30 | - [WooCommerce Integration](#woocommerce-integration)
31 | 9. [Troubleshooting and Solutions](#troubleshooting-and-solutions)
32 | - [Common WordPress-Specific Issues](#common-wordpress-specific-issues)
33 | - [Context Window Limitations with Large Plugins](#context-window-limitations-with-large-plugins)
34 | 10. [Resources and Templates](#resources-and-templates)
35 | - [WordPress Project Context Template](#wordpress-project-context-template)
36 | - [Plugin Development Session Template](#plugin-development-session-template)
37 |
38 | ## Introduction
39 |
40 | This guide will help you set up Cursor, an AI-powered code editor, specifically for WordPress development. We'll focus on plugin development with modern features like Gutenberg blocks and REST API endpoints, ensuring your AI assistant understands the WordPress context and coding standards. By following this guide, you'll establish an efficient workflow that combines the power of AI assistance with WordPress best practices.
41 |
42 | ## Installing and Configuring Cursor
43 |
44 | ### Basic Installation
45 |
46 | 1. **Download and Install Cursor**:
47 | - Visit [cursor.sh](https://cursor.sh) to download the appropriate version for your operating system
48 | - Follow the installation instructions for your platform
49 | - Launch Cursor to complete initial setup
50 |
51 | 2. **Initial Configuration**:
52 | - Connect Cursor to your preferred AI provider if required
53 | - Configure your preferred theme and editor settings
54 | - Set up Git integration for version control
55 |
56 | ### WordPress-Specific Configuration
57 |
58 | 1. **PHP Language Support**:
59 | - Ensure PHP language support is enabled in Cursor
60 | - Configure PHP formatting settings to align with WordPress coding standards
61 | - Consider installing the WordPress extension if available
62 |
63 | 2. **JavaScript/TypeScript Configuration**:
64 | - Configure TypeScript support for Gutenberg block development
65 | - Set up ESLint with WordPress configuration
66 |
67 | 3. **Environment Integration**:
68 | - Configure Cursor to work with your local WordPress development environment
69 | - Set up paths to your WordPress installation
70 |
71 | ## Setting Up Rules for AI
72 |
73 | ### Creating a Rules File
74 |
75 | Cursor's AI can be guided by a rules file that provides context and coding preferences. Create a new file in your project directory named `.cursor/rules.md` to establish guidelines for the AI.
76 |
77 | ### WordPress-Specific Rules Template
78 |
79 | Here's an extended version of the sample rules provided, optimized for WordPress plugin development:
80 |
81 | ```markdown
82 | # Rules for AI in WordPress Development
83 |
84 | - You are operating in a WordPress plugin context, that has a Guzzle-based HTTP client, WP REST endpoint addition(s), and new Gutenberg editor blocks.
85 | - Always use WordPress coding standards when writing PHP, JavaScript, and TypeScript.
86 | - Always type hint PHP code.
87 | - Prefer writing TypeScript over JavaScript.
88 | - Favor functional paradigms over object-oriented ones, favor composition over inheritance, but be consistent with WordPress ecosystem best practices.
89 | - Optimize for readability.
90 |
91 | ## WordPress-Specific Guidelines
92 |
93 | - Use WordPress hooks (actions and filters) appropriately rather than modifying core files.
94 | - Follow the WordPress security best practices including proper data sanitization, validation, and escaping.
95 | - Use WordPress' built-in functions when available instead of writing custom ones.
96 | - Use WordPress' database abstraction layer ($wpdb) for database operations.
97 | - Use WordPress' nonce system for form submissions.
98 | - Follow WordPress plugin directory guidelines for all public plugins.
99 | - Prefer wp_enqueue_script and wp_enqueue_style for asset management.
100 |
101 | ## Coding Standards
102 |
103 | - PHP: Follow PSR-12 with WordPress adaptations.
104 | - JavaScript/TypeScript: Follow WordPress JavaScript coding standards.
105 | - CSS: Follow WordPress CSS coding standards.
106 | - Keep functions focused and small when possible.
107 | - Add appropriate documentation for hooks, functions, and classes.
108 |
109 | ## Development Focus
110 |
111 | - Ensure code is compatible with PHP 7.4+ and follows modern PHP practices.
112 | - Create responsive and accessible Gutenberg blocks.
113 | - Implement proper error handling for API requests.
114 | - Use WordPress transients or object cache for performance optimization when appropriate.
115 | - Follow REST API best practices for endpoint creation.
116 | ```
117 |
118 | ### Explanation of Rules
119 |
120 | Let's break down the key elements of these rules:
121 |
122 | 1. **Context Specification**: Establishes that we're working on a WordPress plugin with specific technologies (Guzzle, REST API, Gutenberg).
123 |
124 | 2. **Coding Standards**: Sets expectations for following WordPress coding standards while incorporating modern practices like type hinting.
125 |
126 | 3. **Technology Preferences**: Establishes TypeScript preference over JavaScript for new code.
127 |
128 | 4. **Architecture Approach**: Guides the AI toward functional paradigms and composition while remaining consistent with WordPress practices.
129 |
130 | 5. **WordPress-Specific Guidelines**: Provides detailed guidance on WordPress-specific practices like hooks, security, and the database layer.
131 |
132 | 6. **Development Focus**: Sets expectations for modern PHP practices, accessibility, error handling, and performance considerations.
133 |
134 | ## Project Structure Organization
135 |
136 | ### WordPress Plugin Structure
137 |
138 | For optimal Cursor AI understanding, ensure your plugin follows a clear, organized structure:
139 |
140 | ```
141 | my-plugin/
142 | │
143 | ├── .cursor/
144 | │ └── rules.md # AI rules file
145 | │
146 | ├── assets/
147 | │ ├── js/ # JavaScript files
148 | │ ├── css/ # CSS files
149 | │ └── images/ # Image files
150 | │
151 | ├── build/ # Compiled Gutenberg blocks
152 | │
153 | ├── src/
154 | │ ├── Blocks/ # Gutenberg block source files
155 | │ ├── REST/ # REST API endpoint implementations
156 | │ ├── Http/ # Guzzle HTTP client implementations
157 | │ └── Utils/ # Utility functions and classes
158 | │
159 | ├── templates/ # Template files
160 | │
161 | ├── vendor/ # Composer dependencies
162 | │
163 | ├── tests/ # Test files
164 | │
165 | ├── composer.json # Composer configuration
166 | ├── package.json # npm configuration
167 | ├── my-plugin.php # Main plugin file
168 | ├── uninstall.php # Uninstall handler
169 | └── README.md # Project documentation
170 | ```
171 |
172 | ### Including Key Files in Context
173 |
174 | To help Cursor understand your project better:
175 |
176 | 1. **Create a project summary file** at the root of your project that explains the plugin's purpose and architecture.
177 |
178 | 2. **Maintain a plugin documentation file** that outlines:
179 | - Plugin hooks provided
180 | - Available filters
181 | - REST API endpoints
182 | - Shortcodes
183 | - Gutenberg blocks
184 |
185 | 3. **Include a WordPress core reference** file that lists common WordPress functions and hooks your plugin uses.
186 |
187 | ## Workflow Best Practices
188 |
189 | ### Plugin Development Workflow
190 |
191 | 1. **Project Initialization**:
192 | ```
193 | I'm developing a WordPress plugin called [PLUGIN_NAME] that [PLUGIN_PURPOSE].
194 |
195 | The main components are:
196 | - [COMPONENT_1]: [PURPOSE]
197 | - [COMPONENT_2]: [PURPOSE]
198 | - [COMPONENT_3]: [PURPOSE]
199 |
200 | Let's start by setting up the plugin's main file.
201 | ```
202 |
203 | 2. **Feature Implementation**:
204 | ```
205 | Now I need to implement [FEATURE_NAME] for our WordPress plugin.
206 |
207 | Requirements:
208 | - [REQUIREMENT_1]
209 | - [REQUIREMENT_2]
210 | - [REQUIREMENT_3]
211 |
212 | It should integrate with WordPress by using [HOOKS/APIS].
213 |
214 | Let's plan and implement this feature.
215 | ```
216 |
217 | 3. **Testing and Debugging**:
218 | ```
219 | I need to test the [FEATURE] functionality in our WordPress plugin.
220 |
221 | Can you help me create:
222 | 1. A list of test cases to verify functionality
223 | 2. Debug code to help troubleshoot issues
224 | 3. A WordPress-specific logging approach for this feature
225 | ```
226 |
227 | ### Gutenberg Block Development
228 |
229 | For Gutenberg block development with Cursor:
230 |
231 | 1. **Block Planning**:
232 | ```
233 | I need to create a new Gutenberg block called [BLOCK_NAME] that allows users to [BLOCK_FUNCTIONALITY].
234 |
235 | The block should:
236 | - Have these attributes: [ATTRIBUTES]
237 | - Support these alignment options: [ALIGNMENTS]
238 | - Have these custom controls: [CONTROLS]
239 |
240 | Let's start by defining the block registration.
241 | ```
242 |
243 | 2. **Block Implementation**:
244 | ```
245 | Now that we've defined the block registration, let's implement:
246 |
247 | 1. The edit component in TypeScript/JSX
248 | 2. The save component
249 | 3. The necessary styles
250 |
251 | The block should follow WordPress accessibility standards and be responsive.
252 | ```
253 |
254 | 3. **Block Testing**:
255 | ```
256 | Now let's create test cases and verification steps for our Gutenberg block:
257 |
258 | 1. Manual testing procedures
259 | 2. Integration with the WordPress editor
260 | 3. Compatibility with other blocks
261 | ```
262 |
263 | ### REST API Endpoint Development
264 |
265 | For developing WordPress REST API endpoints:
266 |
267 | 1. **Endpoint Planning**:
268 | ```
269 | I need to create a custom WordPress REST API endpoint for [PURPOSE].
270 |
271 | The endpoint should:
272 | - Be registered at [ROUTE]
273 | - Support these methods: [METHODS]
274 | - Require these permissions: [PERMISSIONS]
275 | - Accept these parameters: [PARAMETERS]
276 |
277 | Let's plan the implementation.
278 | ```
279 |
280 | 2. **Endpoint Implementation**:
281 | ```
282 | Let's implement the REST API endpoint we planned.
283 |
284 | We need to:
285 | 1. Register the route
286 | 2. Create callback functions for each method
287 | 3. Implement proper request validation
288 | 4. Add response handling with appropriate status codes
289 | 5. Implement WordPress nonce validation
290 |
291 | Let's start with the route registration.
292 | ```
293 |
294 | 3. **Endpoint Testing**:
295 | ```
296 | Now let's create a testing plan for our REST API endpoint:
297 |
298 | 1. Manual testing with appropriate tools (like Postman)
299 | 2. Authentication testing
300 | 3. Error handling testing
301 | 4. Performance testing considerations
302 | ```
303 |
304 | ## Context Management for WordPress
305 |
306 | ### Managing WordPress Core Context
307 |
308 | Since WordPress has a massive codebase, you need strategies to provide relevant context without overflow:
309 |
310 | 1. **Core Function References**:
311 | Create a reference file for commonly used WordPress functions that includes:
312 |
313 | ```markdown
314 | # WordPress Core Functions Reference
315 |
316 | ## Content Functions
317 | - `get_post()`: Retrieves post data given a post ID or post object
318 | - `get_posts()`: Retrieves a list of recent posts
319 |
320 | ## User Functions
321 | - `current_user_can()`: Checks if the current user has a certain capability
322 | - `wp_get_current_user()`: Gets the current user object
323 |
324 | ## Database Functions
325 | - `$wpdb->get_results()`: Retrieves multiple database rows
326 | - `$wpdb->prepare()`: Prepares a SQL query for safe execution
327 |
328 | ## Hook System
329 | - `add_action()`: Hooks a function to a specific action
330 | - `add_filter()`: Hooks a function to a specific filter
331 | ```
332 |
333 | 2. **Just-in-time Context**:
334 | When working on specific WordPress features, provide targeted context:
335 |
336 | ```
337 | For this REST API endpoint, we need to understand these WordPress concepts:
338 |
339 | 1. `register_rest_route()` function for registering endpoints
340 | 2. WordPress permission callback system
341 | 3. WordPress request parameter sanitization
342 |
343 | Let's focus specifically on these aspects for now.
344 | ```
345 |
346 | ### Theme vs Plugin Context
347 |
348 | Be explicit about whether you're working on a theme or plugin:
349 |
350 | ```
351 | Note that we're developing a plugin, not a theme. This means:
352 |
353 | 1. We should use plugin activation/deactivation hooks
354 | 2. We should not include theme-specific functions
355 | 3. Our code needs to work independently of the active theme
356 | 4. We should use plugin-specific loading patterns
357 |
358 | Let's keep this context in mind as we develop.
359 | ```
360 |
361 | ## Prompting Techniques for WordPress Development
362 |
363 | ### Plugin Feature Development
364 |
365 | Use structured prompts for plugin features:
366 |
367 | ```
368 | I need to implement a [FEATURE_TYPE] for my WordPress plugin.
369 |
370 | Specifically, I want to:
371 | - [FEATURE_FUNCTIONALITY]
372 | - It should integrate with [WP_COMPONENT]
373 | - It needs to store data in [DATA_STORAGE_APPROACH]
374 |
375 | WordPress-specific requirements:
376 | - Must use appropriate hooks: [HOOK_EXAMPLES]
377 | - Should follow WordPress security practices for [SECURITY_CONCERN]
378 | - Needs to be compatible with [WP_VERSION] and above
379 |
380 | Let's implement this feature following WordPress best practices.
381 | ```
382 |
383 | ### Debugging WordPress Issues
384 |
385 | For debugging WordPress-specific problems:
386 |
387 | ```
388 | I'm debugging an issue in my WordPress plugin where [PROBLEM_DESCRIPTION].
389 |
390 | Environment details:
391 | - WordPress version: [WP_VERSION]
392 | - PHP version: [PHP_VERSION]
393 | - Relevant plugins: [PLUGINS]
394 |
395 | Error information:
396 | - Error message: [ERROR_MESSAGE]
397 | - Error location: [ERROR_LOCATION]
398 |
399 | What I've tried:
400 | - [TROUBLESHOOTING_STEP_1]
401 | - [TROUBLESHOOTING_STEP_2]
402 |
403 | How can I diagnose and fix this WordPress-specific issue?
404 | ```
405 |
406 | ### Code Optimization and Refactoring
407 |
408 | For optimizing WordPress code:
409 |
410 | ```
411 | I need to optimize this WordPress [CODE_TYPE]:
412 |
413 | ```php
414 | [CODE_SNIPPET]
415 | ```
416 |
417 | Specifically, I'm concerned about:
418 | - [PERFORMANCE_ISSUE]
419 | - [MAINTAINABILITY_ISSUE]
420 | - [WORDPRESS_SPECIFIC_CONCERN]
421 |
422 | Can you help me refactor this following WordPress best practices while maintaining functionality?
423 | ```
424 |
425 | ## Advanced Techniques
426 |
427 | ### Working with Multiple Plugins
428 |
429 | When developing multiple plugins or managing plugin interactions:
430 |
431 | ```
432 | I'm working on two WordPress plugins that need to interact:
433 |
434 | Plugin 1: [PLUGIN_1_NAME]
435 | - Purpose: [PURPOSE]
436 | - Key functions: [FUNCTIONS]
437 |
438 | Plugin 2: [PLUGIN_2_NAME]
439 | - Purpose: [PURPOSE]
440 | - Key functions: [FUNCTIONS]
441 |
442 | I need to implement a way for Plugin 1 to [INTERACTION_DESCRIPTION] with Plugin 2 using WordPress best practices.
443 |
444 | What's the best approach for this plugin interaction?
445 | ```
446 |
447 | ### Theme Development in Cursor
448 |
449 | For theme development context:
450 |
451 | ```
452 | Note that for this session, I'm working on a WordPress theme, not a plugin.
453 |
454 | Theme-specific context:
455 | - Using template hierarchy
456 | - Implementing theme support features
457 | - Working with template parts
458 | - Supporting Gutenberg editor styles
459 |
460 | Let's develop this theme component with these considerations in mind.
461 | ```
462 |
463 | ### WooCommerce Integration
464 |
465 | For WooCommerce-specific development:
466 |
467 | ```
468 | I'm developing a WordPress plugin that integrates with WooCommerce.
469 |
470 | WooCommerce-specific requirements:
471 | - Needs to hook into [WOOCOMMERCE_HOOK]
472 | - Extends [WOOCOMMERCE_COMPONENT]
473 | - Modifies [WOOCOMMERCE_FUNCTIONALITY]
474 |
475 | Let's develop this integration following WooCommerce best practices.
476 | ```
477 |
478 | ## Troubleshooting and Solutions
479 |
480 | ### Common WordPress-Specific Issues
481 |
482 | 1. **Hook Priority Issues**:
483 | ```
484 | I'm having an issue where my plugin's hook isn't executing at the right time.
485 |
486 | Current code:
487 | ```php
488 | add_action('init', 'my_function');
489 | ```
490 |
491 | What I need:
492 | - Function needs to run after [OTHER_PLUGIN] but before theme setup
493 | - Need to understand hook priority system better
494 |
495 | How can I fix this WordPress hook timing issue?
496 | ```
497 |
498 | 2. **Database Query Performance**:
499 | ```
500 | I'm having performance issues with this WordPress database query:
501 |
502 | ```php
503 | $results = $wpdb->get_results("SELECT * FROM {$wpdb->posts} WHERE post_type = 'product'");
504 | ```
505 |
506 | The site has over 10,000 products and this query is slow.
507 |
508 | How can I optimize this query following WordPress best practices?
509 | ```
510 |
511 | ### Context Window Limitations with Large Plugins
512 |
513 | For managing context in large WordPress plugins:
514 |
515 | ```
516 | I'm working on a large WordPress plugin with over 50 files. For this session, let's focus specifically on:
517 |
518 | 1. The payment gateway integration in:
519 | - src/Payments/Gateway.php
520 | - src/Payments/Processor.php
521 |
522 | 2. The specific issue with [FEATURE]
523 |
524 | Let's ignore other plugin components for now to stay within context limits.
525 | ```
526 |
527 | ## Resources and Templates
528 |
529 | ### WordPress Project Context Template
530 |
531 | Use this template to provide project context for Cursor:
532 |
533 | ```markdown
534 | # WordPress Project Context: [PLUGIN_NAME]
535 |
536 | ## Plugin Purpose
537 | [BRIEF_DESCRIPTION]
538 |
539 | ## WordPress Integration Points
540 | - Hooks used: [HOOKS]
541 | - Filters provided: [FILTERS]
542 | - Shortcodes: [SHORTCODES]
543 | - Gutenberg blocks: [BLOCKS]
544 | - REST endpoints: [ENDPOINTS]
545 |
546 | ## Data Storage
547 | - Custom tables: [TABLES]
548 | - Post types: [POST_TYPES]
549 | - Options: [OPTIONS]
550 | - Transients: [TRANSIENTS]
551 |
552 | ## External Services
553 | - [SERVICE_1]: [PURPOSE]
554 | - [SERVICE_2]: [PURPOSE]
555 |
556 | ## Plugin Architecture
557 | [BRIEF_ARCHITECTURE_DESCRIPTION]
558 |
559 | ## Current Development Focus
560 | [CURRENT_FOCUS]
561 | ```
562 |
563 | ### Plugin Development Session Template
564 |
565 | Use this template to start development sessions:
566 |
567 | ```markdown
568 | # Development Session: [DATE]
569 |
570 | ## Current Focus
571 | [FEATURE_OR_COMPONENT]
572 |
573 | ## WordPress Context
574 | - This is a [PLUGIN/THEME] development task
575 | - WordPress version target: [WP_VERSION]+
576 | - Related core components: [WP_COMPONENTS]
577 |
578 | ## Relevant Files
579 | - [FILE_1]: [PURPOSE]
580 | - [FILE_2]: [PURPOSE]
581 |
582 | ## Session Goals
583 | 1. [GOAL_1]
584 | 2. [GOAL_2]
585 |
586 | ## WordPress-Specific Considerations
587 | - [CONSIDERATION_1]
588 | - [CONSIDERATION_2]
589 |
590 | ## Starting Point
591 | [SPECIFIC_STARTING_TASK]
592 | ```
593 |
594 | By following this guide and using these templates, you'll create an effective development environment in Cursor that understands the WordPress context and can assist you in building high-quality plugins following WordPress best practices.
595 |
--------------------------------------------------------------------------------
/Guide for Effective Collaboration with Cursor.md:
--------------------------------------------------------------------------------
1 | # Comprehensive Guide for Effective Collaboration with Cursor
2 |
3 | ## Table of Contents
4 |
5 | 1. [Introduction](#introduction)
6 | 2. [Context Rules for AI in Cursor](#context-rules-for-ai-in-cursor)
7 | - [Understanding Context in Cursor](#understanding-context-in-cursor)
8 | - [What Gets Sent to the AI](#what-gets-sent-to-the-ai)
9 | - [Context Window Limitations](#context-window-limitations)
10 | 3. [Effective Prompting Strategies](#effective-prompting-strategies)
11 | - [The /code Command](#the-code-command)
12 | - [The /edit Command](#the-edit-command)
13 | - [Chat Interface Best Practices](#chat-interface-best-practices)
14 | - [Task-Specific Prompting Templates](#task-specific-prompting-templates)
15 | 4. [Project Context Management](#project-context-management)
16 | - [Setting Up Project Context](#setting-up-project-context)
17 | - [Context Manifests](#context-manifests)
18 | - [Handling Context Overflow](#handling-context-overflow)
19 | 5. [Advanced Cursor Techniques](#advanced-cursor-techniques)
20 | - [File Linking and Referencing](#file-linking-and-referencing)
21 | - [Working with Multiple Files](#working-with-multiple-files)
22 | - [Using Chat History Effectively](#using-chat-history-effectively)
23 | - [Context Prioritization](#context-prioritization)
24 | 6. [Session Management](#session-management)
25 | - [Starting Development Sessions](#starting-development-sessions)
26 | - [Context Restoration Techniques](#context-restoration-techniques)
27 | - [Ending Sessions Effectively](#ending-sessions-effectively)
28 | 7. [Troubleshooting and Solutions](#troubleshooting-and-solutions)
29 | - [Common Context Issues](#common-context-issues)
30 | - [Improving AI Understanding](#improving-ai-understanding)
31 | - [Redirecting Off-Track Implementations](#redirecting-off-track-implementations)
32 | 8. [Templates and Frameworks](#templates-and-frameworks)
33 | - [Project Context Template](#project-context-template)
34 | - [Session Management Templates](#session-management-templates)
35 | - [Code Documentation Templates](#code-documentation-templates)
36 | 9. [Example Workflows](#example-workflows)
37 | - [New Project Development](#new-project-development)
38 | - [Bug Fixing and Debugging](#bug-fixing-and-debugging)
39 | - [Feature Implementation](#feature-implementation)
40 |
41 | ## Introduction
42 |
43 | Cursor is an AI-powered code editor that provides intelligent assistance through context-aware code generation, editing suggestions, and in-editor chat capabilities. This guide focuses on maximizing your collaboration with Cursor's AI by understanding its context rules, applying effective prompting strategies, and managing project context effectively.
44 |
45 | The primary goal of this guide is to help you work within Cursor's context system, ensuring the AI has the information it needs to provide helpful, accurate assistance while avoiding context overflow and maintaining an efficient workflow.
46 |
47 | ## Context Rules for AI in Cursor
48 |
49 | ### Understanding Context in Cursor
50 |
51 | Cursor's AI doesn't just respond to your immediate query—it uses multiple sources of context to understand your project and your intent:
52 |
53 | 1. **Active File Context**: The file you're currently working on provides immediate context
54 | 2. **Project Context**: Files within your project that relate to your current task
55 | 3. **Editor Context**: Your selected code, cursor position, and visible editor panes
56 | 4. **Chat History**: Previous exchanges within the current session
57 | 5. **Language and Framework Knowledge**: The AI's built-in understanding of programming
58 |
59 | Understanding how Cursor prioritizes and manages these context sources is crucial for effective collaboration.
60 |
61 | ### What Gets Sent to the AI
62 |
63 | By default, Cursor sends the following to the AI:
64 |
65 | 1. **Current File**: The entire content of the file you're working in
66 | 2. **Selected Code**: Any code you've highlighted
67 | 3. **Related Files**: Other project files that Cursor determines are relevant
68 | 4. **Chat History**: Previous messages in the current chat session
69 | 5. **Command Context**: Special commands like `/code` and `/edit` provide additional context
70 |
71 | Important considerations:
72 |
73 | - Not every file in your project is sent to the AI due to context limits
74 | - The AI prioritizes files directly related to your current work
75 | - You can explicitly reference or link files to include them in context
76 |
77 | ### Context Window Limitations
78 |
79 | Cursor's AI operates within a finite context window, which limits how much information it can process at once:
80 |
81 | - Context is measured in tokens (roughly 4 characters per token)
82 | - The context limit varies based on the AI model being used
83 | - When context exceeds limits, Cursor must make decisions about what to keep and what to drop
84 |
85 | To avoid context overflow:
86 |
87 | 1. **Be specific in your queries**
88 | 2. **Focus on one task at a time**
89 | 3. **Reference only the most relevant files**
90 | 4. **Break large tasks into smaller subtasks**
91 | 5. **Use context management techniques described later in this guide**
92 |
93 | ## Effective Prompting Strategies
94 |
95 | ### The /code Command
96 |
97 | The `/code` command is one of the most powerful features in Cursor. It generates code based on your prompt and current context.
98 |
99 | Best practices for `/code`:
100 |
101 | 1. **Be specific and concise**:
102 | ```
103 | /code Create a React component that displays a paginated list of users with search functionality. It should use the fetchUsers API from api.js and handle loading and error states.
104 | ```
105 |
106 | 2. **Specify language or framework explicitly**:
107 | ```
108 | /code Generate a Python function that processes CSV data using pandas, filtering out rows that don't meet the specified criteria
109 | ```
110 |
111 | 3. **Provide scope and interfaces**:
112 | ```
113 | /code The function should take a filename and filter_criteria dictionary as parameters and return a filtered DataFrame. It should handle file not found errors gracefully.
114 | ```
115 |
116 | 4. **Include examples when useful**:
117 | ```
118 | /code Example input: filter_criteria = {'age': 30, 'status': 'active'}
119 | This should filter the CSV to only include rows where age > 30 AND status == 'active'
120 | ```
121 |
122 | ### The /edit Command
123 |
124 | The `/edit` command allows you to modify existing code. It's powerful for refactoring, bug fixing, and adding features.
125 |
126 | Best practices for `/edit`:
127 |
128 | 1. **Define clear boundaries**:
129 | ```
130 | /edit Refactor the processUserData function below to use async/await instead of promises
131 | ```
132 |
133 | 2. **Specify the goal, not just the method**:
134 | ```
135 | /edit Update this function to include rate limiting to prevent API abuse. Max 5 requests per minute per user.
136 | ```
137 |
138 | 3. **Indicate preservation requirements**:
139 | ```
140 | /edit Add input validation to this function without changing the core business logic
141 | ```
142 |
143 | 4. **Reference existing code patterns**:
144 | ```
145 | /edit Update this component following the same error handling pattern used in LoginForm.jsx
146 | ```
147 |
148 | ### Chat Interface Best Practices
149 |
150 | When using Cursor's chat interface:
151 |
152 | 1. **Start with context summary**:
153 | ```
154 | I'm working on the user authentication module that uses JWT tokens. I need to add password reset functionality.
155 | ```
156 |
157 | 2. **Use clear, consistent terminology**:
158 | ```
159 | Can you explain how the 'validateUser' function in auth.js interacts with the 'UserSession' class?
160 | ```
161 |
162 | 3. **One request per message**:
163 | Break complex requests into individual messages rather than asking multiple questions at once.
164 |
165 | 4. **Reference files explicitly**:
166 | ```
167 | In src/utils/validation.js, what's the purpose of the sanitizeInput function and where is it being used?
168 | ```
169 |
170 | 5. **Provide feedback on responses**:
171 | Let the AI know when its suggestions are helpful or off-track to improve future interactions.
172 |
173 | ### Task-Specific Prompting Templates
174 |
175 | Adapt these templates for common development tasks:
176 |
177 | 1. **Feature Implementation**:
178 | ```
179 | I need to implement [FEATURE_NAME].
180 |
181 | Requirements:
182 | - [REQUIREMENT_1]
183 | - [REQUIREMENT_2]
184 | - [REQUIREMENT_3]
185 |
186 | It should interact with these existing components:
187 | - [COMPONENT_1] in [FILE_PATH_1]
188 | - [COMPONENT_2] in [FILE_PATH_2]
189 |
190 | Please help me plan and implement this feature.
191 | ```
192 |
193 | 2. **Bug Fixing**:
194 | ```
195 | I'm debugging an issue where [PROBLEM_DESCRIPTION].
196 |
197 | Expected behavior: [WHAT_SHOULD_HAPPEN]
198 | Actual behavior: [WHAT_ACTUALLY_HAPPENS]
199 |
200 | Relevant code:
201 | - The issue appears to be in [FILE_PATH], around line [LINE_NUMBER]
202 | - It's related to [FUNCTION/COMPONENT_NAME]
203 |
204 | What could be causing this issue and how can I fix it?
205 | ```
206 |
207 | 3. **Code Review**:
208 | ```
209 | Can you review this implementation of [FEATURE/FUNCTION]?
210 |
211 | Focus on:
212 | - Performance optimization
213 | - Security concerns
214 | - Edge cases
215 | - Code readability
216 |
217 | [CODE_OR_FILE_REFERENCE]
218 | ```
219 |
220 | ## Project Context Management
221 |
222 | ### Setting Up Project Context
223 |
224 | Create a project context document to help Cursor understand your project structure and architecture:
225 |
226 | ```markdown
227 | # Project Context: [PROJECT_NAME]
228 |
229 | ## Architecture Overview
230 | - Frontend: [TECHNOLOGIES]
231 | - Backend: [TECHNOLOGIES]
232 | - Database: [TECHNOLOGIES]
233 | - Authentication: [METHOD]
234 |
235 | ## Key Components
236 | - [COMPONENT_1]: [PURPOSE] - [FILE_PATH]
237 | - [COMPONENT_2]: [PURPOSE] - [FILE_PATH]
238 | - [COMPONENT_3]: [PURPOSE] - [FILE_PATH]
239 |
240 | ## Data Flow
241 | [BRIEF_DESCRIPTION_OF_DATA_FLOW]
242 |
243 | ## External APIs/Services
244 | - [API_1]: [PURPOSE]
245 | - [API_2]: [PURPOSE]
246 |
247 | ## Project Conventions
248 | - [CONVENTION_1]
249 | - [CONVENTION_2]
250 | ```
251 |
252 | Keep this document in your project root and reference it when starting new sessions with Cursor.
253 |
254 | ### Context Manifests
255 |
256 | For larger projects, create focused context manifests for specific modules or features:
257 |
258 | ```markdown
259 | # Context Manifest: [MODULE_NAME]
260 |
261 | ## Purpose
262 | [MODULE_PURPOSE]
263 |
264 | ## Key Files
265 | - [FILE_1]: [PURPOSE]
266 | - [FILE_2]: [PURPOSE]
267 | - [FILE_3]: [PURPOSE]
268 |
269 | ## Dependencies
270 | - Internal: [INTERNAL_DEPENDENCIES]
271 | - External: [EXTERNAL_DEPENDENCIES]
272 |
273 | ## API/Interface
274 | [DESCRIPTION_OF_MODULE_INTERFACE]
275 |
276 | ## Current State
277 | - [IMPLEMENTED_FEATURES]
278 | - [PENDING_FEATURES]
279 | - [KNOWN_ISSUES]
280 | ```
281 |
282 | Use these manifests to provide targeted context when working on specific parts of your project.
283 |
284 | ### Handling Context Overflow
285 |
286 | When working with large codebases that exceed context limits:
287 |
288 | 1. **Create a context hierarchy**:
289 | - Project-level context (high-level structure and relationships)
290 | - Module-level context (specific components or features)
291 | - File-level context (implementation details)
292 |
293 | 2. **Use targeted context loading**:
294 | ```
295 | For this session, we'll focus on the user authentication module. The relevant files are:
296 | - src/auth/AuthProvider.js
297 | - src/auth/useAuth.js
298 | - src/auth/authUtils.js
299 | - src/api/authApi.js
300 |
301 | Let's start by examining AuthProvider.js to understand the authentication flow.
302 | ```
303 |
304 | 3. **Create context snapshots**:
305 | Document the current state of development at key milestones to help restore context later.
306 |
307 | ## Advanced Cursor Techniques
308 |
309 | ### File Linking and Referencing
310 |
311 | To bring specific files into Cursor's context:
312 |
313 | 1. **Explicit file references**:
314 | ```
315 | I need help understanding how the data flows from api.js to UserProfile.jsx
316 | ```
317 |
318 | 2. **File content sharing**:
319 | When a file isn't automatically included in context, share relevant portions:
320 | ```
321 | Here's the utility function from utils/formatting.js that's causing issues:
322 |
323 | ```js
324 | export function formatCurrency(amount, currency = 'USD') {
325 | // Function implementation
326 | }
327 | ```
328 | ```
329 |
330 | 3. **Dependency mapping**:
331 | ```
332 | The component I'm working on depends on:
333 | 1. The AuthContext from src/context/AuthContext.js
334 | 2. The API client from src/api/client.js
335 | 3. The useForm hook from our custom hooks library
336 | ```
337 |
338 | ### Working with Multiple Files
339 |
340 | Strategies for multi-file tasks:
341 |
342 | 1. **Sequential context building**:
343 | ```
344 | Let's start by understanding the database schema in models/user.js, then we'll look at the controller in controllers/userController.js, and finally the routes in routes/userRoutes.js
345 | ```
346 |
347 | 2. **Relationship focus**:
348 | ```
349 | I need to understand how these three files interact:
350 | - Component.jsx renders the UI
351 | - useDataHook.js fetches and processes data
352 | - apiService.js makes the actual API calls
353 |
354 | Let's trace a user action from the UI to the API and back.
355 | ```
356 |
357 | 3. **Implementation planning**:
358 | ```
359 | This feature will require changes to:
360 | 1. The database model (models/product.js)
361 | 2. The API endpoint (controllers/productController.js)
362 | 3. The frontend component (components/ProductForm.jsx)
363 |
364 | Let's plan the changes needed for each file.
365 | ```
366 |
367 | ### Using Chat History Effectively
368 |
369 | Cursor maintains chat history within the session context. Use it effectively:
370 |
371 | 1. **Reference previous discussions**:
372 | ```
373 | As we discussed earlier about the authentication flow, I now need to implement the password reset functionality.
374 | ```
375 |
376 | 2. **Incremental development**:
377 | Build on previous work without repeating context:
378 | ```
379 | Now that we've implemented the basic validation, let's add the more advanced rules we discussed.
380 | ```
381 |
382 | 3. **Context reinforcement**:
383 | Periodically summarize progress to reinforce important context:
384 | ```
385 | So far we've:
386 | 1. Implemented the data model
387 | 2. Created the API endpoints
388 | 3. Started the UI components
389 |
390 | Let's now focus on connecting the UI to the API.
391 | ```
392 |
393 | ### Context Prioritization
394 |
395 | Help Cursor prioritize the most relevant context:
396 |
397 | 1. **Explicit prioritization**:
398 | ```
399 | The most important file for this task is src/components/DataTable.jsx. It uses helpers from src/utils/tableUtils.js and gets data via src/hooks/useDataFetch.js.
400 | ```
401 |
402 | 2. **Function-level focus**:
403 | ```
404 | Let's focus specifically on the `processTransactionData` function in dataUtils.js. It's called by the Dashboard and Reports components.
405 | ```
406 |
407 | 3. **Interface emphasis**:
408 | ```
409 | The key interface we're working with is the `UserService` class in services/userService.js. Let's understand its public methods before we modify it.
410 | ```
411 |
412 | ## Session Management
413 |
414 | ### Starting Development Sessions
415 |
416 | Begin each session with proper context initialization:
417 |
418 | ```
419 | I'm continuing work on [PROJECT_NAME].
420 |
421 | Current focus: [CURRENT_TASK]
422 |
423 | Key files for this session:
424 | - [FILE_1]: [PURPOSE]
425 | - [FILE_2]: [PURPOSE]
426 | - [FILE_3]: [PURPOSE]
427 |
428 | Progress so far:
429 | - [COMPLETED_ITEM_1]
430 | - [COMPLETED_ITEM_2]
431 |
432 | Today, I want to accomplish:
433 | - [GOAL_1]
434 | - [GOAL_2]
435 |
436 | Let's start by [SPECIFIC_STARTING_POINT].
437 | ```
438 |
439 | ### Context Restoration Techniques
440 |
441 | When resuming work after breaks or in new sessions:
442 |
443 | 1. **Project state summary**:
444 | ```
445 | We've been developing a user management system. So far, we've implemented:
446 | - User registration and login
447 | - Profile management
448 | - Basic role permissions
449 |
450 | We're currently working on the advanced permissions system.
451 | ```
452 |
453 | 2. **Recent development recap**:
454 | ```
455 | In our last session, we:
456 | - Created the PermissionGroup model
457 | - Started implementing the permission assignment UI
458 | - Identified an issue with permission inheritance
459 |
460 | Let's pick up by resolving that inheritance issue.
461 | ```
462 |
463 | 3. **Code evolution explanation**:
464 | ```
465 | The authentication system has evolved through several iterations:
466 | 1. Basic email/password (completed)
467 | 2. Addition of social login (completed)
468 | 3. Multi-factor authentication (in progress)
469 |
470 | We're working on step 3, specifically the verification code handling.
471 | ```
472 |
473 | ### Ending Sessions Effectively
474 |
475 | Conclude sessions with a structured wrap-up:
476 |
477 | ```
478 | Let's summarize what we've accomplished today:
479 |
480 | 1. Implemented:
481 | - [IMPLEMENTATION_1]
482 | - [IMPLEMENTATION_2]
483 |
484 | 2. Issues resolved:
485 | - [ISSUE_1]
486 | - [ISSUE_2]
487 |
488 | 3. Pending items for next session:
489 | - [PENDING_ITEM_1]
490 | - [PENDING_ITEM_2]
491 |
492 | 4. Notes for context:
493 | - [IMPORTANT_CONTEXT_1]
494 | - [IMPORTANT_CONTEXT_2]
495 |
496 | Is there anything else you'd recommend I focus on in our next session?
497 | ```
498 |
499 | ## Troubleshooting and Solutions
500 |
501 | ### Common Context Issues
502 |
503 | 1. **AI Missing Important Context**
504 |
505 | Problem: Cursor's AI gives suggestions that don't align with your project's architecture or conventions.
506 |
507 | Solution:
508 | ```
509 | I notice you might be missing some important context about our project. Key things to know:
510 |
511 | 1. We're using Repository pattern for data access
512 | 2. Authentication is handled via JSON Web Tokens
513 | 3. We follow the container/component pattern for React components
514 |
515 | With this in mind, could you revise your suggestion for the user profile feature?
516 | ```
517 |
518 | 2. **Context Overflow**
519 |
520 | Problem: You're working on a large project and Cursor is struggling with the context amount.
521 |
522 | Solution:
523 | ```
524 | Let's narrow our focus for this task. We'll only consider:
525 |
526 | 1. The payment processing module (src/payments/*)
527 | 2. The specific issue with transaction reconciliation
528 |
529 | We can ignore the user management and reporting features for now.
530 | ```
531 |
532 | 3. **Inconsistent Understanding**
533 |
534 | Problem: Cursor seems to understand some parts of your project but not others.
535 |
536 | Solution:
537 | ```
538 | Let me clarify our project structure:
539 |
540 | Frontend:
541 | - React components in src/components
542 | - Redux store in src/store
543 | - Utilities in src/utils
544 |
545 | Backend:
546 | - Express routes in routes/
547 | - Controllers in controllers/
548 | - Models in models/
549 |
550 | Does this help establish a clearer understanding?
551 | ```
552 |
553 | ### Improving AI Understanding
554 |
555 | When Cursor's responses indicate misunderstanding:
556 |
557 | 1. **Provide concrete examples**:
558 | ```
559 | Let me show you how we typically implement API services:
560 |
561 | ```js
562 | // Example from src/services/productService.js
563 | export class ProductService {
564 | async getProducts(filters) {
565 | // Implementation
566 | }
567 |
568 | async createProduct(productData) {
569 | // Implementation
570 | }
571 | }
572 | ```
573 |
574 | Please follow this pattern for the new UserService.
575 | ```
576 |
577 | 2. **Contrast with alternatives**:
578 | ```
579 | We're using React Query for data fetching, NOT Redux. This means:
580 | - Data fetching is done with useQuery hooks
581 | - Mutations use useMutation hooks
582 | - We don't have actions/reducers for API calls
583 |
584 | Please adjust your approach accordingly.
585 | ```
586 |
587 | 3. **Feedback on incorrect assumptions**:
588 | ```
589 | There are a few misunderstandings in your response:
590 |
591 | 1. We're using MongoDB, not PostgreSQL
592 | 2. Our authentication is JWT-based, not session-based
593 | 3. Frontend routing is done with React Router, not Next.js
594 |
595 | Could you revise your suggestion with these corrections?
596 | ```
597 |
598 | ### Redirecting Off-Track Implementations
599 |
600 | When Cursor's implementation goes in the wrong direction:
601 |
602 | ```
603 | Let's redirect our approach. The current implementation won't work because:
604 |
605 | 1. [ISSUE_1]
606 | 2. [ISSUE_2]
607 |
608 | Instead, we should:
609 |
610 | 1. [ALTERNATIVE_APPROACH_1]
611 | 2. [ALTERNATIVE_APPROACH_2]
612 |
613 | The key requirements to keep in mind are:
614 | - [KEY_REQUIREMENT_1]
615 | - [KEY_REQUIREMENT_2]
616 |
617 | Let's try again with this direction.
618 | ```
619 |
620 | ## Templates and Frameworks
621 |
622 | ### Project Context Template
623 |
624 | ```markdown
625 | # Project Context: [PROJECT_NAME]
626 |
627 | ## Overview
628 | [PROJECT_DESCRIPTION]
629 |
630 | ## Architecture
631 | - Frontend: [FRONTEND_TECH]
632 | - Backend: [BACKEND_TECH]
633 | - Database: [DATABASE_TECH]
634 | - Deployment: [DEPLOYMENT_STRATEGY]
635 |
636 | ## Key Features
637 | - [FEATURE_1]: [DESCRIPTION]
638 | - [FEATURE_2]: [DESCRIPTION]
639 | - [FEATURE_3]: [DESCRIPTION]
640 |
641 | ## Project Structure
642 | - [DIRECTORY_1]/: [PURPOSE]
643 | - [DIRECTORY_2]/: [PURPOSE]
644 | - [DIRECTORY_3]/: [PURPOSE]
645 |
646 | ## Naming Conventions
647 | - [CONVENTION_1]
648 | - [CONVENTION_2]
649 |
650 | ## Testing Approach
651 | - [TESTING_STRATEGY]
652 |
653 | ## Important Dependencies
654 | - [DEPENDENCY_1]: [PURPOSE]
655 | - [DEPENDENCY_2]: [PURPOSE]
656 | ```
657 |
658 | ### Session Management Templates
659 |
660 | 1. **Session Initialization**:
661 | ```markdown
662 | # Session: [DATE]
663 |
664 | ## Focus Area
665 | [FEATURE_OR_COMPONENT]
666 |
667 | ## Relevant Files
668 | - [FILE_1]: [PURPOSE]
669 | - [FILE_2]: [PURPOSE]
670 |
671 | ## Context
672 | [BACKGROUND_INFORMATION]
673 |
674 | ## Goals
675 | 1. [GOAL_1]
676 | 2. [GOAL_2]
677 |
678 | ## Starting Point
679 | [SPECIFIC_STARTING_TASK]
680 | ```
681 |
682 | 2. **Progress Tracker**:
683 | ```markdown
684 | # Progress Update
685 |
686 | ## Completed
687 | - [TASK_1] ✅
688 | - [TASK_2] ✅
689 |
690 | ## In Progress
691 | - [TASK_3] 🔄
692 | - [TASK_4] 🔄
693 |
694 | ## Not Started
695 | - [TASK_5] ⏳
696 | - [TASK_6] ⏳
697 |
698 | ## Issues/Blockers
699 | - [ISSUE_1] ❌
700 | - [ISSUE_2] ❌
701 | ```
702 |
703 | 3. **Session Summary**:
704 | ```markdown
705 | # Session Summary: [DATE]
706 |
707 | ## Accomplishments
708 | - [ACCOMPLISHMENT_1]
709 | - [ACCOMPLISHMENT_2]
710 |
711 | ## Code Changes
712 | - [FILE_1]: [CHANGES]
713 | - [FILE_2]: [CHANGES]
714 |
715 | ## Decisions Made
716 | - [DECISION_1]
717 | - [DECISION_2]
718 |
719 | ## Next Steps
720 | 1. [NEXT_STEP_1]
721 | 2. [NEXT_STEP_2]
722 |
723 | ## Notes for Next Session
724 | - [NOTE_1]
725 | - [NOTE_2]
726 | ```
727 |
728 | ### Code Documentation Templates
729 |
730 | 1. **Function Documentation**:
731 | ```javascript
732 | /**
733 | * @function [FUNCTION_NAME]
734 | * @description [DESCRIPTION]
735 | *
736 | * @param {[TYPE]} [PARAM_NAME] - [DESCRIPTION]
737 | * @param {[TYPE]} [PARAM_NAME] - [DESCRIPTION]
738 | *
739 | * @returns {[TYPE]} [DESCRIPTION]
740 | *
741 | * @example
742 | * // Example usage
743 | * const result = functionName(param1, param2);
744 | */
745 | ```
746 |
747 | 2. **Component Documentation**:
748 | ```javascript
749 | /**
750 | * @component [COMPONENT_NAME]
751 | * @description [DESCRIPTION]
752 | *
753 | * @prop {[TYPE]} [PROP_NAME] - [DESCRIPTION]
754 | * @prop {[TYPE]} [PROP_NAME] - [DESCRIPTION]
755 | *
756 | * @example
757 | * // Example usage
758 | *
759 | *
760 | * @notes
761 | * - [NOTE_1]
762 | * - [NOTE_2]
763 | */
764 | ```
765 |
766 | 3. **Context Comments**:
767 | ```javascript
768 | // [CONTEXT:START]
769 | // This module handles user authentication
770 | // It connects to the Auth service and manages user sessions
771 | // Key responsibilities:
772 | // - Login/logout functionality
773 | // - Session persistence
774 | // - Authentication state management
775 | // [CONTEXT:END]
776 | ```
777 |
778 | ## Example Workflows
779 |
780 | ### New Project Development
781 |
782 | 1. **Project Setup Phase**
783 | - Create project structure
784 | - Document architecture decisions in the Project Context template
785 | - Establish coding conventions
786 | - Set up initial files
787 |
788 | 2. **Development Phase**
789 | - Break features into manageable tasks
790 | - For each task:
791 | - Provide specific context for the task
792 | - Use `/code` for initial implementation
793 | - Review and refine with `/edit`
794 | - Document code with appropriate templates
795 | - Update Progress Tracker as you complete tasks
796 |
797 | 3. **Iteration Phase**
798 | - Begin each session with Session Initialization
799 | - End each session with Session Summary
800 | - Maintain the Project Context document as the project evolves
801 |
802 | ### Bug Fixing and Debugging
803 |
804 | 1. **Issue Identification**
805 | ```
806 | I'm debugging an issue where [PROBLEM_DESCRIPTION].
807 |
808 | Steps to reproduce:
809 | 1. [STEP_1]
810 | 2. [STEP_2]
811 | 3. [STEP_3]
812 |
813 | Expected: [EXPECTED_BEHAVIOR]
814 | Actual: [ACTUAL_BEHAVIOR]
815 |
816 | Error message: [ERROR_MESSAGE]
817 | ```
818 |
819 | 2. **Context Gathering**
820 | ```
821 | The issue appears to be in [COMPONENT_OR_FILE].
822 |
823 | Relevant code:
824 | ```[LANGUAGE]
825 | [CODE_SNIPPET]
826 | ```
827 |
828 | Related components:
829 | - [COMPONENT_1] calls this code when [EVENT]
830 | - [COMPONENT_2] depends on the output of this code
831 | ```
832 |
833 | 3. **Problem Analysis**
834 | ```
835 | Based on the error and code, I think the issue might be related to:
836 |
837 | 1. [POSSIBLE_CAUSE_1]
838 | 2. [POSSIBLE_CAUSE_2]
839 |
840 | Can you help diagnose which is more likely?
841 | ```
842 |
843 | 4. **Solution Implementation**
844 | ```
845 | Can you suggest a fix for this issue that:
846 |
847 | 1. Resolves the immediate error
848 | 2. Prevents similar issues in the future
849 | 3. Maintains compatibility with the rest of the system
850 | ```
851 |
852 | ### Feature Implementation
853 |
854 | 1. **Feature Planning**
855 | ```
856 | I need to implement [FEATURE_NAME].
857 |
858 | Requirements:
859 | - [REQUIREMENT_1]
860 | - [REQUIREMENT_2]
861 | - [REQUIREMENT_3]
862 |
863 | It needs to integrate with:
864 | - [EXISTING_COMPONENT_1]
865 | - [EXISTING_COMPONENT_2]
866 |
867 | What's the best approach for implementing this?
868 | ```
869 |
870 | 2. **Architecture Definition**
871 | ```
872 | Based on our discussion, let's use this architecture for the feature:
873 |
874 | 1. Data model: [DATA_MODEL_DESCRIPTION]
875 | 2. API endpoints: [ENDPOINTS_DESCRIPTION]
876 | 3. Service layer: [SERVICE_LAYER_DESCRIPTION]
877 | 4. UI components: [UI_COMPONENTS_DESCRIPTION]
878 |
879 | Let's start by implementing the data model.
880 | ```
881 |
882 | 3. **Incremental Implementation**
883 | ```
884 | Now that we've implemented the data model, let's move on to the API endpoints.
885 |
886 | For context, remember that:
887 | - The data model has these fields: [FIELDS]
888 | - We need to support these operations: [OPERATIONS]
889 | - Authentication is required for all endpoints
890 |
891 | Let's implement the CRUD endpoints for this feature.
892 | ```
893 |
894 | 4. **Integration and Testing**
895 | ```
896 | With the backend components in place, let's implement the UI.
897 |
898 | The UI should:
899 | - Display [DATA] in a [COMPONENT_TYPE]
900 | - Allow users to [USER_ACTIONS]
901 | - Handle loading and error states
902 | - Follow our application's design patterns
903 |
904 | Let's start with the main component structure.
905 | ```
906 |
907 | By following these guidelines and using the templates provided, you'll maximize the effectiveness of your collaboration with Cursor, ensuring that the AI has the context it needs to provide helpful, relevant assistance throughout your development process.
908 |
--------------------------------------------------------------------------------
/Claude Code MCP Guide.md:
--------------------------------------------------------------------------------
1 | # Claude Code MCP Guide: Enhancing Memory and Sequential Thinking
2 |
3 | ## Table of Contents
4 |
5 | 1. [Introduction](#introduction)
6 | 2. [Understanding the MCP Framework](#understanding-the-mcp-framework)
7 | - [Memory](#memory)
8 | - [Context](#context)
9 | - [Planning](#planning)
10 | 3. [Setting Up Claude Code for MCP](#setting-up-claude-code-for-mcp)
11 | - [Installation and Configuration](#installation-and-configuration)
12 | - [Project Structure for Sequential Thinking](#project-structure-for-sequential-thinking)
13 | 4. [Memory Enhancement Techniques](#memory-enhancement-techniques)
14 | - [State Tracking Files](#state-tracking-files)
15 | - [Session Journals](#session-journals)
16 | - [Contextual Breadcrumbs](#contextual-breadcrumbs)
17 | 5. [Sequential Thinking Frameworks](#sequential-thinking-frameworks)
18 | - [Task Decomposition Strategies](#task-decomposition-strategies)
19 | - [Step-by-Step Execution Model](#step-by-step-execution-model)
20 | - [Verification Checkpoints](#verification-checkpoints)
21 | 6. [Practical MCP Implementation](#practical-mcp-implementation)
22 | - [Starting an MCP Session](#starting-an-mcp-session)
23 | - [Maintaining State Between Interactions](#maintaining-state-between-interactions)
24 | - [Context Restoration After Interruptions](#context-restoration-after-interruptions)
25 | 7. [Advanced Techniques](#advanced-techniques)
26 | - [Structured Reasoning Chains](#structured-reasoning-chains)
27 | - [Long-Running Tasks with Checkpointing](#long-running-tasks-with-checkpointing)
28 | - [Multi-Stage Problem Solving](#multi-stage-problem-solving)
29 | 8. [MCP Templates and Patterns](#mcp-templates-and-patterns)
30 | - [Project State Template](#project-state-template)
31 | - [Sequential Task Template](#sequential-task-template)
32 | - [Reasoning Chain Template](#reasoning-chain-template)
33 | 9. [Case Studies and Examples](#case-studies-and-examples)
34 | - [Multi-Step Refactoring Project](#multi-step-refactoring-project)
35 | - [Sequential Feature Implementation](#sequential-feature-implementation)
36 | - [Debugging Complex Issues](#debugging-complex-issues)
37 | 10. [Troubleshooting MCP Issues](#troubleshooting-mcp-issues)
38 | - [Handling Context Loss](#handling-context-loss)
39 | - [Recovering from Reasoning Errors](#recovering-from-reasoning-errors)
40 | - [Optimizing Context Usage](#optimizing-context-usage)
41 |
42 | ## Introduction
43 |
44 | Claude Code is an AI-powered command-line tool that assists with software development tasks. While powerful, AI assistants naturally face challenges with maintaining long-term memory and thinking sequentially across multiple steps. This guide introduces the Memory, Context, and Planning (MCP) framework—a methodology designed to enhance Claude Code's ability to handle complex, multi-stage tasks through structured approaches to memory management and sequential thinking.
45 |
46 | The MCP framework helps Claude Code overcome inherent limitations of AI assistants by creating explicit memory structures, managing context efficiently, and implementing deliberate planning strategies. This approach transforms Claude Code from a reactive tool into a more effective partner for complex software development projects.
47 |
48 | ## Understanding the MCP Framework
49 |
50 | ### Memory
51 |
52 | Memory in the MCP framework refers to the deliberate recording and referencing of information, decisions, and state across interactions. Unlike human memory, Claude Code doesn't inherently "remember" previous work, so the MCP framework creates explicit memory structures:
53 |
54 | - **Short-term memory**: Information needed within the current task sequence
55 | - **Long-term memory**: Project-wide knowledge that persists across sessions
56 | - **Working memory**: The active set of considerations for the current step
57 |
58 | Enhancing Claude Code's memory isn't about technical modifications to the AI, but rather implementing workflows and documentation practices that simulate memory.
59 |
60 | ### Context
61 |
62 | Context refers to the relevant information Claude Code needs to understand the current state of work:
63 |
64 | - **Project context**: Overall project goals, architecture, and standards
65 | - **Task context**: The specific task at hand, its requirements, and constraints
66 | - **Historical context**: Previous decisions and their rationales
67 | - **Technical context**: Language-specific, framework-specific, or domain-specific considerations
68 |
69 | Managing context effectively means strategically controlling what information is provided to Claude Code at any given time, ensuring it has the right information without exceeding context window limitations.
70 |
71 | ### Planning
72 |
73 | Planning involves breaking down complex tasks into manageable sequences and establishing a clear path forward:
74 |
75 | - **Task decomposition**: Breaking large problems into smaller, sequential steps
76 | - **Dependency management**: Identifying which tasks must precede others
77 | - **Verification strategies**: Defining how to validate successful completion of each step
78 | - **Adaptive planning**: Adjusting plans based on intermediate results
79 |
80 | Effective planning allows Claude Code to focus on one step at a time while maintaining awareness of the overall goal.
81 |
82 | ## Setting Up Claude Code for MCP
83 |
84 | ### Installation and Configuration
85 |
86 | 1. **Install Claude Code**:
87 | - Follow the standard installation instructions for Claude Code
88 | - Ensure you have the latest version for best performance
89 |
90 | 2. **Create an MCP Project Directory Structure**:
91 | ```
92 | project/
93 | ├── .claude/
94 | │ ├── state.md # Tracks current project state
95 | │ ├── memory/ # Directory for persistent memory files
96 | │ │ ├── decisions.md # Records key decisions
97 | │ │ ├── progress.md # Tracks overall progress
98 | │ │ └── tasks/ # Individual task memory files
99 | │ ├── sessions/ # Session journals
100 | │ └── templates/ # MCP templates
101 | ├── src/ # Your actual project code
102 | ├── docs/ # Project documentation
103 | └── README.md # Project overview
104 | ```
105 |
106 | 3. **Configure Shell Integration** (optional):
107 | - Create aliases for common MCP patterns
108 | - Set up environment variables for project paths
109 |
110 | ### Project Structure for Sequential Thinking
111 |
112 | Organize your project to support sequential thinking:
113 |
114 | 1. **Task Breakdown Files**:
115 | Create a `tasks.md` file that explicitly breaks down large features into sequential steps:
116 |
117 | ```markdown
118 | # Feature: User Authentication System
119 |
120 | ## Sequential Implementation Plan
121 |
122 | 1. [ ] Define user data model
123 | a. [ ] Design database schema
124 | b. [ ] Create model classes
125 | c. [ ] Implement validation
126 |
127 | 2. [ ] Implement authentication logic
128 | a. [ ] Password hashing and verification
129 | b. [ ] Session management
130 | c. [ ] Token generation
131 |
132 | 3. [ ] Create API endpoints
133 | a. [ ] Registration endpoint
134 | b. [ ] Login endpoint
135 | c. [ ] Password reset flow
136 |
137 | 4. [ ] Frontend integration
138 | a. [ ] Create authentication forms
139 | b. [ ] Implement client-side validation
140 | c. [ ] Add auth state management
141 | ```
142 |
143 | 2. **Stage-Based Directories**:
144 | For complex projects, consider organizing code by development stages:
145 |
146 | ```
147 | feature/
148 | ├── stage1-data-model/
149 | ├── stage2-auth-logic/
150 | ├── stage3-api-endpoints/
151 | └── stage4-frontend/
152 | ```
153 |
154 | This organization reinforces sequential development and makes it easier for Claude Code to understand the current stage.
155 |
156 | ## Memory Enhancement Techniques
157 |
158 | ### State Tracking Files
159 |
160 | Create and maintain state files that Claude Code can reference:
161 |
162 | ```markdown
163 | # Project State: User Authentication System
164 | Last Updated: 2025-03-15
165 |
166 | ## Current Stage: 2b - Session Management
167 |
168 | ## Completed Steps:
169 | - ✅ 1a: Designed user schema with fields: id, username, email, password_hash, created_at, last_login
170 | - ✅ 1b: Created User model with basic attributes
171 | - ✅ 1c: Implemented validation for email and password strength
172 | - ✅ 2a: Implemented bcrypt password hashing and verification
173 |
174 | ## Current Work:
175 | - 🔄 2b: Implementing session management
176 | - Created session table in database
177 | - Implemented session creation
178 | - TODO: Session expiration handling
179 | - TODO: Implement remember-me functionality
180 |
181 | ## Next Steps:
182 | - 2c: Token generation for API authentication
183 | - 3a: User registration endpoint
184 |
185 | ## Key Decisions:
186 | - Using JWT for API authentication
187 | - Sessions stored in database rather than Redis (revisit if scale requires)
188 | - Password reset tokens valid for 24 hours
189 |
190 | ## Known Issues:
191 | - Need to add rate limiting for login attempts
192 | ```
193 |
194 | Update this file after each significant development step and reference it at the beginning of new Claude Code sessions.
195 |
196 | ### Session Journals
197 |
198 | Maintain detailed session journals to track work done with Claude Code:
199 |
200 | ```markdown
201 | # Session Journal: 2025-03-15
202 |
203 | ## Session Goals
204 | - Complete session management implementation
205 | - Begin token generation functionality
206 |
207 | ## Work Completed
208 | - Implemented session expiration handling
209 | - Added `expires_at` column to sessions table
210 | - Created cleanup cron job
211 | - Added forced expiration on password change
212 | - Started remember-me functionality
213 | - Added persistent token storage
214 | - Implemented auto-renewal of sessions
215 |
216 | ## Challenges Encountered
217 | - Edge case with multiple active sessions per user
218 | - Solution: Added session listing and management UI
219 |
220 | ## Next Session Plan
221 | - Complete remember-me functionality
222 | - Begin implementation of JWT token generation
223 |
224 | ## Code Changes
225 | - Modified `SessionManager.php`: Added expiration logic
226 | - Created `SessionCleanup.php`: Implemented cron job
227 | - Updated `LoginController.php`: Added remember-me checkbox handling
228 | ```
229 |
230 | Share relevant parts of these journals when resuming work with Claude Code to help it understand what was previously accomplished.
231 |
232 | ### Contextual Breadcrumbs
233 |
234 | Leave explicit breadcrumbs in your code for Claude Code to follow:
235 |
236 | ```php
237 | // [MCP:MEMORY] 2025-03-15: Implemented basic session creation
238 | // [MCP:MEMORY] 2025-03-15: Added session expiration handling
239 | // [MCP:MEMORY] 2025-03-16: Implemented remember-me functionality
240 | // [MCP:TODO] Add session invalidation on password change
241 |
242 | public function createSession(User $user, bool $rememberMe = false): Session
243 | {
244 | // Implementation...
245 | }
246 | ```
247 |
248 | These breadcrumbs create a timeline within the code itself, helping Claude Code understand the evolution of the codebase.
249 |
250 | ## Sequential Thinking Frameworks
251 |
252 | ### Task Decomposition Strategies
253 |
254 | 1. **Hierarchical Decomposition**:
255 | Break tasks down into a hierarchy of steps and substeps:
256 |
257 | ```
258 | Task: Implement User Authentication
259 | ├── Step 1: Design Data Models
260 | │ ├── Step 1.1: Define user schema
261 | │ ├── Step 1.2: Define session schema
262 | │ └── Step 1.3: Define relationships
263 | ├── Step 2: Implement Core Logic
264 | │ ├── ...
265 | ```
266 |
267 | 2. **Pipeline Decomposition**:
268 | Organize tasks as data flowing through a pipeline:
269 |
270 | ```
271 | Raw User Input → Validation → Authentication → Session Creation → Response
272 | ```
273 |
274 | 3. **State-Based Decomposition**:
275 | Define tasks in terms of state transitions:
276 |
277 | ```
278 | Anonymous → Credentials Provided → Validated → Authenticated → Session Established
279 | ```
280 |
281 | When working with Claude Code, explicitly describe which decomposition strategy you're using and the current position within it.
282 |
283 | ### Step-by-Step Execution Model
284 |
285 | Implement a clear execution model for working through sequential tasks:
286 |
287 | 1. **Setup Phase**:
288 | ```
289 | I'm implementing user authentication following our sequential plan.
290 | We're currently at Step 2b: Session Management.
291 |
292 | Previous steps completed:
293 | - Designed database schema
294 | - Created models
295 | - Implemented password hashing
296 |
297 | In this step, we need to:
298 | 1. Create session storage
299 | 2. Implement session creation on login
300 | 3. Add session validation
301 | 4. Handle session expiration
302 |
303 | Let's start with subtask 1: Creating session storage.
304 | ```
305 |
306 | 2. **Execution Phase**:
307 | For each subtask:
308 |
309 | ```
310 | Let's implement subtask 1: Creating session storage.
311 |
312 | We need to:
313 | - Define a sessions table
314 | - Create a Session model
315 | - Add methods for session CRUD operations
316 |
317 | Let's begin with the database schema.
318 | ```
319 |
320 | 3. **Verification Phase**:
321 | After completing each subtask:
322 |
323 | ```
324 | We've now implemented the session storage with:
325 | - Sessions table with fields: id, user_id, token, expires_at, ip_address, user_agent
326 | - Session model with creation and validation methods
327 | - Repository pattern for session management
328 |
329 | Let's verify this implementation:
330 |
331 | 1. The schema includes all necessary fields for tracking and security ✅
332 | 2. The model properly encapsulates session logic ✅
333 | 3. We've included methods for creating, validating, and expiring sessions ✅
334 |
335 | This subtask is complete. Let's move to subtask 2: Implementing session creation on login.
336 | ```
337 |
338 | 4. **Transition Phase**:
339 | Explicitly transition to the next subtask:
340 |
341 | ```
342 | Now that we've completed session storage, let's implement session creation during user login.
343 |
344 | For context, here's our login flow:
345 | 1. User submits credentials
346 | 2. We validate credentials (already implemented)
347 | 3. We need to create a session (current task)
348 | 4. Return session token to user
349 |
350 | Let's focus on step 3...
351 | ```
352 |
353 | ### Verification Checkpoints
354 |
355 | Implement explicit verification at multiple levels:
356 |
357 | 1. **Subtask Verification**:
358 | After each small step, verify correctness:
359 |
360 | ```
361 | I've implemented the session creation method. Let's verify it:
362 |
363 | Requirements:
364 | - Must create a unique token ✅
365 | - Must set appropriate expiration ✅
366 | - Must store IP and user agent ✅
367 | - Must invalidate old sessions if limit reached ✅
368 |
369 | The implementation meets all requirements.
370 | ```
371 |
372 | 2. **Task Verification**:
373 | After completing a major task:
374 |
375 | ```
376 | We've now completed the entire session management system. Let's verify against our requirements:
377 |
378 | 1. Sessions are securely created with random tokens ✅
379 | 2. Sessions expire appropriately ✅
380 | 3. Users can have multiple sessions ✅
381 | 4. Remember-me functionality extends sessions ✅
382 | 5. Sessions are properly validated on each request ✅
383 |
384 | All requirements are met. Let's update our project state to mark this task complete and move to the next step: JWT token generation.
385 | ```
386 |
387 | 3. **Integration Verification**:
388 | Verify that completed components work together:
389 |
390 | ```
391 | Now that we've implemented both session management and JWT token generation, let's verify they work together properly:
392 |
393 | Test scenario: User logs in
394 | 1. Credentials validated ✅
395 | 2. Session created in database ✅
396 | 3. JWT token generated with correct payload ✅
397 | 4. Token returned to user ✅
398 | 5. User can access protected resources with token ✅
399 |
400 | The integration is working as expected.
401 | ```
402 |
403 | ## Practical MCP Implementation
404 |
405 | ### Starting an MCP Session
406 |
407 | When starting a new Claude Code session, include comprehensive context:
408 |
409 | ```
410 | I'm continuing development on our user authentication system using the MCP framework for sequential development.
411 |
412 | Here's our current project state:
413 |
414 |
415 | Today, we'll be working on Stage 2c: JWT token generation.
416 |
417 | Specifically, we need to:
418 | 1. Set up a secure key for JWT signing
419 | 2. Implement token generation with proper claims
420 | 3. Create token validation middleware
421 | 4. Add token refresh functionality
422 |
423 | Let's start with step 1: Setting up a secure key for JWT signing.
424 | ```
425 |
426 | ### Maintaining State Between Interactions
427 |
428 | Between Claude Code interactions in the same session:
429 |
430 | 1. **Summarize Progress**:
431 | ```
432 | We've now completed the JWT key setup by:
433 | - Generating a secure key
434 | - Storing it in environment variables
435 | - Adding a configuration provider
436 |
437 | Next, let's move to step 2: Implementing token generation with proper claims.
438 | ```
439 |
440 | 2. **Provide Transition Context**:
441 | ```
442 | For token generation, we need to consider:
443 | - What user data should be included in the token
444 | - Token expiration time
445 | - Refresh token strategy
446 |
447 | Let's implement the JWTService class that will handle token generation.
448 | ```
449 |
450 | 3. **Update State Documents**:
451 | After significant progress, update your state tracking file and reference the changes:
452 |
453 | ```
454 | I've updated our project state file to reflect the completion of JWT key setup.
455 |
456 | Current state:
457 |
458 |
459 | Now, let's continue with token generation.
460 | ```
461 |
462 | ### Context Restoration After Interruptions
463 |
464 | If your Claude Code session is interrupted or you need to start a new session:
465 |
466 | 1. **Explicit Restoration Point**:
467 | ```
468 | I need to restore our previous Claude Code session on the authentication system.
469 |
470 | We were working on JWT token generation and had completed:
471 | - Setting up the secure signing key
472 | - Defining the token structure
473 |
474 | We were in the middle of implementing the token generation method in JWTService.php.
475 |
476 | Here's the code we had so far:
477 |
478 | ```php
479 | public function generateToken(User $user): string
480 | {
481 | // Define standard claims
482 | $issuedAt = new DateTimeImmutable();
483 | $expire = $issuedAt->modify('+15 minutes');
484 |
485 | // TODO: Add custom claims
486 | // TODO: Implement signing
487 | }
488 | ```
489 |
490 | Let's continue by implementing the custom claims and token signing.
491 | ```
492 |
493 | 2. **Session Journal Reference**:
494 | ```
495 | According to our session journal from yesterday:
496 |
497 |
498 |
499 | We need to pick up by implementing the token refresh functionality.
500 | ```
501 |
502 | 3. **State Reestablishment**:
503 | ```
504 | Before continuing, let's make sure we're aligned on the current state of the authentication system:
505 |
506 |
507 |
508 | Given this state, we'll now focus on implementing the token refresh endpoint.
509 | ```
510 |
511 | ## Advanced Techniques
512 |
513 | ### Structured Reasoning Chains
514 |
515 | Implement explicit reasoning chains for complex decisions:
516 |
517 | ```
518 | Let's think through our token refresh strategy step by step:
519 |
520 | 1. Problem: JWT tokens need to be short-lived for security, but we want to avoid forcing users to log in frequently.
521 |
522 | 2. Options:
523 | A. Single refresh token with long expiry
524 | B. Rotating refresh tokens
525 | C. Sliding expiration window
526 |
527 | 3. Analysis:
528 | - Option A is simplest but has security implications if the refresh token is compromised
529 | - Option B is more secure as refresh tokens change after each use
530 | - Option C provides good UX but requires more server-side state
531 |
532 | 4. Trade-offs:
533 | - Security vs. Implementation Complexity
534 | - User Experience vs. Security
535 |
536 | 5. Decision criteria:
537 | - We need high security for this financial application
538 | - Implementation complexity is acceptable for security benefits
539 | - User experience should be good but security takes priority
540 |
541 | 6. Decision:
542 | We'll implement Option B: Rotating refresh tokens, because:
543 | - Provides best security by limiting the lifetime of any single token
544 | - Allows us to invalidate specific refresh token chains if needed
545 | - Acceptable implementation complexity for the security benefits
546 |
547 | 7. Implementation approach:
548 | - Store refresh tokens in the database with reference to the parent token
549 | - Implement token rotation on each refresh
550 | - Add token family concept to prevent replay attacks
551 |
552 | Let's proceed with implementing this approach.
553 | ```
554 |
555 | ### Long-Running Tasks with Checkpointing
556 |
557 | For tasks that span multiple sessions, implement checkpointing:
558 |
559 | 1. **Define Checkpoints**:
560 | ```
561 | We're implementing the entire authentication system, which will take multiple sessions. Let's define checkpoints:
562 |
563 | - Checkpoint 1: Data models and basic validation ✅
564 | - Checkpoint 2: Core authentication logic
565 | - 2.1: Password handling ✅
566 | - 2.2: Session management ✅
567 | - 2.3: JWT implementation 🔄
568 | - Checkpoint 3: API endpoints
569 | - Checkpoint 4: Frontend integration
570 |
571 | We're currently at Checkpoint 2.3: JWT implementation.
572 | ```
573 |
574 | 2. **Checkpoint State Files**:
575 | Create dedicated state files for each checkpoint in `.claude/memory/checkpoints/`
576 |
577 | 3. **Checkpoint Verification**:
578 | Before moving to a new checkpoint:
579 |
580 | ```
581 | Before moving to Checkpoint 3, let's verify Checkpoint 2 is complete:
582 |
583 | 2.1 Password handling:
584 | - Secure hashing implemented ✅
585 | - Password validation rules established ✅
586 | - Password reset flow created ✅
587 |
588 | 2.2 Session management:
589 | - Session creation and storage implemented ✅
590 | - Session validation working ✅
591 | - Remember-me functionality working ✅
592 |
593 | 2.3 JWT implementation:
594 | - Secure key management implemented ✅
595 | - Token generation with proper claims working ✅
596 | - Token validation middleware created ✅
597 | - Refresh token rotation implemented ✅
598 |
599 | All items in Checkpoint 2 are complete. We can now proceed to Checkpoint 3: API endpoints.
600 | ```
601 |
602 | ### Multi-Stage Problem Solving
603 |
604 | For complex problems, implement a formal multi-stage approach:
605 |
606 | 1. **Understanding Stage**:
607 | ```
608 | We need to implement a secure password reset flow. Let's start by understanding the problem:
609 |
610 | Requirements:
611 | - Users should be able to request a password reset via email
612 | - Reset links should be secure and time-limited
613 | - Users should set a new password that meets our requirements
614 | - Old sessions should be invalidated after password change
615 |
616 | Security considerations:
617 | - Token must be sufficiently random and unguessable
618 | - Process should be resistant to enumeration attacks
619 | - Rate limiting should prevent abuse
620 |
621 | Let's make sure we fully understand the problem before proceeding to design.
622 | ```
623 |
624 | 2. **Design Stage**:
625 | ```
626 | Now that we understand the password reset requirements, let's design the solution:
627 |
628 | Components needed:
629 | 1. Password reset request endpoint
630 | 2. Token generation and storage mechanism
631 | 3. Email service integration
632 | 4. Token verification endpoint
633 | 5. Password update mechanism
634 | 6. Session invalidation logic
635 |
636 | Data model changes:
637 | - Add password_reset_token field to user table
638 | - Add password_reset_expires field to user table
639 |
640 | Flow design:
641 | [User requests reset] → [Generate token, store, send email] → [User clicks link] → [Verify token] → [User sets new password] → [Update password, invalidate token and sessions]
642 |
643 | Let's validate this design before implementation.
644 | ```
645 |
646 | 3. **Implementation Stage**:
647 | Break down and implement each component sequentially using step-by-step execution.
648 |
649 | 4. **Verification Stage**:
650 | ```
651 | Now that we've implemented the password reset flow, let's verify it against our requirements:
652 |
653 | Functional verification:
654 | - Request endpoint returns success and sends email ✅
655 | - Email contains correct reset link ✅
656 | - Invalid or expired tokens are rejected ✅
657 | - Password update enforces validation rules ✅
658 | - Old sessions are invalidated after password change ✅
659 |
660 | Security verification:
661 | - Tokens are cryptographically secure (32 bytes random) ✅
662 | - Tokens are time-limited (1 hour expiry) ✅
663 | - Rate limiting prevents brute force (5 attempts per hour) ✅
664 | - Success/failure messages don't leak account existence ✅
665 |
666 | The implementation meets all functional and security requirements.
667 | ```
668 |
669 | ## MCP Templates and Patterns
670 |
671 | ### Project State Template
672 |
673 | ```markdown
674 | # Project State: [Project Name]
675 | Last Updated: [Date]
676 |
677 | ## Overview
678 | [Brief description of the project]
679 |
680 | ## Current Stage
681 | [Current implementation stage or feature]
682 |
683 | ## Progress Tracking
684 | - [Category 1]:
685 | - ✅ [Completed task 1]
686 | - ✅ [Completed task 2]
687 | - 🔄 [In-progress task]
688 | - ⏳ [Planned task 1]
689 | - ⏳ [Planned task 2]
690 |
691 | - [Category 2]:
692 | - ✅ [Completed task 1]
693 | - 🔄 [In-progress task]
694 | - ⏳ [Planned task]
695 |
696 | ## Current Focus
697 | [Detailed description of the current task]
698 |
699 | ### Subtasks
700 | - [ ] [Subtask 1]
701 | - [ ] [Subtask 2]
702 | - [ ] [Subtask 3]
703 |
704 | ## Key Decisions
705 | - [Decision 1]: [Rationale]
706 | - [Decision 2]: [Rationale]
707 |
708 | ## Dependencies
709 | - [Dependency 1]: [Status]
710 | - [Dependency 2]: [Status]
711 |
712 | ## Known Issues
713 | - [Issue 1]: [Workaround or plan]
714 | - [Issue 2]: [Workaround or plan]
715 |
716 | ## Next Steps
717 | 1. [Next step 1]
718 | 2. [Next step 2]
719 | 3. [Next step 3]
720 | ```
721 |
722 | ### Sequential Task Template
723 |
724 | ```markdown
725 | # Sequential Task: [Task Name]
726 |
727 | ## Objective
728 | [Clear statement of what needs to be accomplished]
729 |
730 | ## Prerequisites
731 | - [Prerequisite 1]
732 | - [Prerequisite 2]
733 |
734 | ## Sequential Steps
735 |
736 | ### 1. [Step 1 Name]
737 | - Description: [Step description]
738 | - Inputs: [What this step needs]
739 | - Expected output: [What should be produced]
740 | - Verification criteria:
741 | - [Criterion 1]
742 | - [Criterion 2]
743 |
744 | ### 2. [Step 2 Name]
745 | - Description: [Step description]
746 | - Inputs: [What this step needs]
747 | - Expected output: [What should be produced]
748 | - Verification criteria:
749 | - [Criterion 1]
750 | - [Criterion 2]
751 |
752 | ### 3. [Step 3 Name]
753 | - Description: [Step description]
754 | - Inputs: [What this step needs]
755 | - Expected output: [What should be produced]
756 | - Verification criteria:
757 | - [Criterion 1]
758 | - [Criterion 2]
759 |
760 | ## Integration Verification
761 | - [Verification step 1]
762 | - [Verification step 2]
763 |
764 | ## Completion Criteria
765 | - [Criterion 1]
766 | - [Criterion 2]
767 | ```
768 |
769 | ### Reasoning Chain Template
770 |
771 | ```markdown
772 | # Reasoning Chain: [Decision Topic]
773 |
774 | ## Problem Statement
775 | [Clear definition of the problem or decision needed]
776 |
777 | ## Context
778 | - [Relevant context 1]
779 | - [Relevant context 2]
780 | - [Relevant context 3]
781 |
782 | ## Options
783 | 1. [Option 1]
784 | - Description: [Description]
785 | - Pros: [List of pros]
786 | - Cons: [List of cons]
787 |
788 | 2. [Option 2]
789 | - Description: [Description]
790 | - Pros: [List of pros]
791 | - Cons: [List of cons]
792 |
793 | 3. [Option 3]
794 | - Description: [Description]
795 | - Pros: [List of pros]
796 | - Cons: [List of cons]
797 |
798 | ## Evaluation Criteria
799 | - [Criterion 1]: [Weight/Importance]
800 | - [Criterion 2]: [Weight/Importance]
801 | - [Criterion 3]: [Weight/Importance]
802 |
803 | ## Analysis
804 | [Step-by-step analysis of options against criteria]
805 |
806 | ## Decision
807 | [The chosen option]
808 |
809 | ## Rationale
810 | [Detailed explanation of why this option was chosen]
811 |
812 | ## Implementation Plan
813 | 1. [Step 1]
814 | 2. [Step 2]
815 | 3. [Step 3]
816 |
817 | ## Future Considerations
818 | - [Consideration 1]
819 | - [Consideration 2]
820 | ```
821 |
822 | ## Case Studies and Examples
823 |
824 | ### Multi-Step Refactoring Project
825 |
826 | **Scenario**: Refactoring a legacy authentication system to a modern implementation using the MCP framework.
827 |
828 | 1. **Initial State Assessment**:
829 | ```
830 | We're refactoring the legacy authentication system. Let's analyze its current state:
831 |
832 | Current implementation:
833 | - Plain MD5 password hashing (security issue)
834 | - Single-file procedural code (maintainability issue)
835 | - No separation of concerns (architectural issue)
836 | - Sessions in PHP's default session store (scalability issue)
837 |
838 | Our refactoring will follow this sequence:
839 | 1. Create proper data models and repositories
840 | 2. Implement secure password hashing with migration strategy
841 | 3. Add proper session management
842 | 4. Implement JWT for API authentication
843 | 5. Refactor UI components to use new system
844 |
845 | Let's start with step 1: Creating proper data models.
846 | ```
847 |
848 | 2. **Sequential Execution**:
849 | For each step, follow the Step-by-Step Execution Model with clear transitions.
850 |
851 | 3. **Maintaining MCP Framework**:
852 | - Update state tracking after each major step
853 | - Maintain session journals
854 | - Use reasoning chains for architectural decisions
855 | - Implement verification at each stage
856 |
857 | 4. **Example Transition**:
858 | ```
859 | We've now completed the user model and repository refactoring. Let's verify:
860 |
861 | - User data structure properly encapsulated ✅
862 | - Repository pattern implemented for data access ✅
863 | - Unit tests added for core functionality ✅
864 | - Legacy code can still function during transition ✅
865 |
866 | Step 1 is complete. Let's update our project state and move to step 2: Implementing secure password hashing with a migration strategy.
867 |
868 | For this step, we need to:
869 | a. Choose a secure hashing algorithm (bcrypt)
870 | b. Create a strategy for migrating existing passwords
871 | c. Implement transparent password upgrade during login
872 |
873 | Let's start with 2a: Choosing and implementing a secure hashing algorithm.
874 | ```
875 |
876 | ### Sequential Feature Implementation
877 |
878 | **Scenario**: Implementing a new feature using the MCP framework for sequential thinking.
879 |
880 | 1. **Feature Decomposition**:
881 | ```
882 | We're implementing a new "Team Permissions" feature. Let's break it down sequentially:
883 |
884 | 1. Data model phase:
885 | a. Create team entity
886 | b. Create team membership model
887 | c. Create permission definition model
888 | d. Create role model with permissions
889 |
890 | 2. Core logic phase:
891 | a. Implement team CRUD operations
892 | b. Implement team membership management
893 | c. Implement permission checking logic
894 | d. Implement role assignment
895 |
896 | 3. API phase:
897 | a. Create team management endpoints
898 | b. Create membership endpoints
899 | c. Create role and permission endpoints
900 |
901 | 4. UI phase:
902 | a. Implement team management interfaces
903 | b. Implement member management
904 | c. Implement permission configuration UI
905 |
906 | Let's start with phase 1a: Creating the team entity.
907 | ```
908 |
909 | 2. **Phase Progression**:
910 | Use explicit phase transitions with verification:
911 |
912 | ```
913 | We've now completed the data model phase (1a-1d). Let's verify:
914 |
915 | - Team entity with proper attributes ✅
916 | - Team membership model with user relationships ✅
917 | - Permission definitions with scopes ✅
918 | - Role model with permission assignments ✅
919 |
920 | All data models are properly implemented with migrations, validations, and tests.
921 |
922 | Now let's move to phase 2: Core logic implementation, starting with 2a: Team CRUD operations.
923 | ```
924 |
925 | 3. **Cross-Reference Previous Work**:
926 | ```
927 | As we implement the permission checking logic (2c), we need to reference the permission model we created in step 1c.
928 |
929 | The permission model has these attributes:
930 | - name: String (e.g., "create_project")
931 | - description: String
932 | - scope: String (e.g., "team", "global")
933 |
934 | Now, let's implement the permission check method that will determine if a user has a specific permission within a team context.
935 | ```
936 |
937 | ### Debugging Complex Issues
938 |
939 | **Scenario**: Using MCP framework for debugging a complex issue.
940 |
941 | 1. **Problem Decomposition**:
942 | ```
943 | We're debugging an issue where users occasionally lose access to their teams after password reset. Let's apply sequential thinking:
944 |
945 | 1. Understanding phase:
946 | a. Define the exact symptoms
947 | b. Identify the conditions under which it occurs
948 | c. Determine affected components
949 |
950 | 2. Investigation phase:
951 | a. Analyze the password reset flow
952 | b. Analyze the team access mechanism
953 | c. Examine the session handling
954 |
955 | 3. Root cause identification phase
956 |
957 | 4. Solution implementation phase
958 |
959 | Let's start with 1a: Defining the exact symptoms.
960 | ```
961 |
962 | 2. **Sequential Investigation**:
963 | ```
964 | Having completed the understanding phase, we now know:
965 | - Only affects users who belong to multiple teams
966 | - Only happens after password reset, not regular login
967 | - User sessions are properly invalidated, but team access is inconsistent
968 |
969 | Now moving to investigation phase 2a: Analyzing the password reset flow.
970 |
971 | Let's trace through the exact code execution during password reset:
972 | 1. User requests password reset
973 | 2. Reset token is generated and stored
974 | 3. User clicks email link and sets new password
975 | 4. Password is updated
976 | 5. All user sessions are invalidated
977 | 6. User is logged in with new session
978 | 7. Team access is loaded
979 |
980 | Let's examine each step...
981 | ```
982 |
983 | 3. **Root Cause Analysis**:
984 | Use structured reasoning chains to identify the root cause:
985 |
986 | ```
987 | After investigation, we've identified three potential root causes:
988 |
989 | 1. Session invalidation issue:
990 | - The new session may not have all required data
991 | - Evidence: Session data differs between regular login and post-reset login
992 |
993 | 2. Team cache problem:
994 | - Team memberships may be cached and not refreshed
995 | - Evidence: Database shows correct memberships but application doesn't
996 |
997 | 3. Race condition:
998 | - Team data might be loaded before user data is fully initialized
999 | - Evidence: Timing differences in log timestamps
1000 |
1001 | Let's analyze each hypothesis...
1002 |
1003 | [Analysis details]
1004 |
1005 | Based on our analysis, the root cause is #3: A race condition where team data is loaded before user data is fully initialized after password reset.
1006 | ```
1007 |
1008 | 4. **Solution Implementation**:
1009 | ```
1010 | Now that we've identified the race condition, let's implement the solution sequentially:
1011 |
1012 | 1. First, let's add proper synchronization between user initialization and team data loading
1013 | 2. Then, let's add explicit refresh of team memberships after login
1014 | 3. Finally, let's add logging to verify the fix
1015 |
1016 | Starting with step 1...
1017 | ```
1018 |
1019 | ## Troubleshooting MCP Issues
1020 |
1021 | ### Handling Context Loss
1022 |
1023 | When Claude Code loses important context:
1024 |
1025 | 1. **Recovery Strategy**:
1026 | ```
1027 | I notice that we may have lost some context about our current task. Let's restore:
1028 |
1029 | We're implementing the team permissions feature and were working on the role assignment API endpoint.
1030 |
1031 | Key context:
1032 | - We've already implemented the data models and core logic
1033 | - The role model has: id, name, team_id, and permissions (JSON)
1034 | - We're using middleware for authentication and permission checking
1035 | - We need to implement the role-user assignment endpoint
1036 |
1037 | Let's continue with implementing this endpoint.
1038 | ```
1039 |
1040 | 2. **Context Prioritization**:
1041 | ```
1042 | Since we have limited context space, let's focus only on the most relevant information for the current task:
1043 |
1044 | For the role assignment endpoint, we need:
1045 | 1. The role assignment controller method
1046 | 2. Request validation
1047 | 3. Permission checking
1048 | 4. Database transaction handling
1049 |
1050 | Let's implement these components sequentially.
1051 | ```
1052 |
1053 | 3. **Context Refresh**:
1054 | Periodically refresh key context:
1055 |
1056 | ```
1057 | Before moving to the next API endpoint, let's refresh our understanding of the authentication flow:
1058 |
1059 | 1. Request contains JWT in Authorization header
1060 | 2. Auth middleware validates the token
1061 | 3. User is loaded and attached to request
1062 | 4. Permission middleware checks specific permissions
1063 |
1064 | This context will be important as we implement the next endpoint.
1065 | ```
1066 |
1067 | ### Recovering from Reasoning Errors
1068 |
1069 | When Claude Code makes errors in sequential reasoning:
1070 |
1071 | 1. **Error Identification**:
1072 | ```
1073 | I notice a problem in our reasoning about the role permission checking. The current implementation:
1074 |
1075 | ```php
1076 | public function hasPermission(User $user, string $permission): bool
1077 | {
1078 | return $user->roles->contains(function($role) use ($permission) {
1079 | return in_array($permission, $role->permissions);
1080 | });
1081 | }
1082 | ```
1083 |
1084 | The error is that permissions are stored as a JSON string in the database, but we're treating them as an array. Let's correct this reasoning.
1085 | ```
1086 |
1087 | 2. **Backtracking**:
1088 | ```
1089 | Let's backtrack to where we designed the permission storage:
1090 |
1091 | We decided to store permissions as a JSON array in the database:
1092 |
1093 | ```php
1094 | $table->json('permissions')->default('[]');
1095 | ```
1096 |
1097 | This means we need to decode the JSON before checking permissions. Let's correct our implementation.
1098 | ```
1099 |
1100 | 3. **Forward Correction**:
1101 | ```
1102 | With the corrected understanding, let's fix the implementation:
1103 |
1104 | ```php
1105 | public function hasPermission(User $user, string $permission): bool
1106 | {
1107 | return $user->roles->contains(function($role) use ($permission) {
1108 | $permissions = json_decode($role->permissions, true);
1109 | return in_array($permission, $permissions);
1110 | });
1111 | }
1112 | ```
1113 |
1114 | Now let's verify this corrected implementation...
1115 | ```
1116 |
1117 | ### Optimizing Context Usage
1118 |
1119 | Strategies for managing limited context windows:
1120 |
1121 | 1. **Targeted Context Loading**:
1122 | ```
1123 | For this session, we'll focus specifically on the team invitation system. The relevant components are:
1124 |
1125 | 1. InvitationController.php: Handles invitation creation and acceptance
1126 | 2. InvitationService.php: Core business logic for invitations
1127 | 3. Invitation.php: The invitation model
1128 | 4. mail/team-invitation.blade.php: Email template
1129 |
1130 | Let's limit our discussion to these components to optimize context usage.
1131 | ```
1132 |
1133 | 2. **Progressive Context Building**:
1134 | ```
1135 | Let's progressively build our understanding of the notification system:
1136 |
1137 | First, let's examine the notification model and database structure...
1138 | [Implement and discuss]
1139 |
1140 | Now that we understand the data layer, let's look at the notification service...
1141 | [Implement and discuss]
1142 |
1143 | With both the data layer and service understood, let's implement the controllers...
1144 | ```
1145 |
1146 | 3. **Deliberate Context Dropping**:
1147 | ```
1148 | Now that we've completed the team management API, we can set aside that context and focus on the notification system.
1149 |
1150 | Let's explicitly transition our focus to the notification components:
1151 |
1152 | 1. Notification models and database structure
1153 | 2. Notification service for creating and managing notifications
1154 | 3. Real-time notification delivery via WebSockets
1155 |
1156 | Let's start with the notification models.
1157 | ```
1158 |
1159 | By implementing the MCP framework with Claude Code, you can significantly enhance its ability to manage complex, multi-step development tasks. The structured approach to memory, context, and planning transforms Claude Code from a reactive assistant into a more effective development partner with improved sequential reasoning capabilities.
1160 |
--------------------------------------------------------------------------------