Serena Instructions to work around memory problems, mainly in Claude Desktop

[riccorohl]

Hi, over many iterations I have come up with an .md file that seems to be useful for Claude when working with serena, after running into the issues when continuously working over several sessions, mostly broken code when starting a new session. I made it mandatory to run type-check on each run.

Honestly, I don't know what most of this document even means. But I had Claude create it for me and it works much better between sessions, it probably has many more fixes.

I'm making a discussion as recommended by a dev that reached out to me on Reddit. Good job guys, keep it up!

I'm just gonna paste it:

Universal Serena Project Instructions Template

🚨 CRITICAL SESSION START PROTOCOL - NO EXCEPTIONS

MANDATORY FIRST STEPS

1. COMPILATION CHECK FIRST

   npm run build  # OR your project's build command
   # OR npm run type-check / tsc --noEmit

2. CRITICAL DECISION TREE:

   • ✅ Build succeeds → Proceed with development
   • ❌ Build has errors → STOP and ask user what needs fixing
   • ❌ Can't run build → Ask user to confirm compilation status

3. NEVER assume something needs fixing without evidence

SESSION CONTEXT SETUP

• Read latest checkpoint description
• Check project status from memories
• Ask user what specific work is needed
• Verify understanding of current session goals

🛠️ FIRST SESSION SETUP REQUIREMENTS

Essential Development Scripts Setup

For TypeScript/React/Next.js projects, ALWAYS ensure these scripts exist in package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build", 
    "start": "next start",
    "lint": "next lint",
    "lint:fix": "next lint --fix",
    "type-check": "tsc --noEmit",
    "type-check:watch": "tsc --noEmit --watch",
    "check-all": "npm run type-check && npm run lint"
  }
}

Enhanced TypeScript Configuration

Add these strict settings to tsconfig.json for professional development:

{
  "compilerOptions": {
    "strict": true,
    "noEmit": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

Professional Development Workflow Documentation

Create memory documenting the enhanced workflow:

• npm run type-check:watch for continuous checking
• npm run check-all before commits
• npm run lint:fix for auto-formatting
• Windows 11 compatibility verification

🔧 CORE DEVELOPMENT PRINCIPLES

THE READ BEFORE WRITE RULE

• ALWAYS read complete file content before modifications
• Search for existing imports/functions before adding new ones
• Use symbolic tools to understand code structure first
• Verify current file structure and dependencies

ASK BEFORE ASSUMING PROTOCOL

• "What specific issue are you experiencing?"
• "What error messages are you seeing?"
• "Which files need modification?"
• NEVER start "fixing" without explicit direction

TYPE-FIRST DEVELOPMENT (TypeScript Projects)

• Define interfaces/types before implementing components
• Types drive implementation, not vice versa
• Fix type definitions instead of adding duplicate properties
• Run compilation checks every 30 minutes during development

🚫 ABSOLUTE PROHIBITIONS

DO NOT:

• Add imports without checking existing ones first
• "Fix" files that aren't broken
• Make changes based on assumptions
• Modify files without reading them completely
• Create duplicate imports/properties under any circumstances
• Use blind find/replace operations

ALWAYS DO:

• Verify current state before any action
• Ask for clarification when uncertain
• Read complete files before editing
• Use precise, targeted modifications
• Test compilation after changes

📋 SESSION WORKFLOW

Session Start Checklist

• Run build/compilation command
• Verify enhanced development scripts exist
• Read latest checkpoint description
• Check memories for project context
• Ask user for today's specific goals
• Verify all systems compile before starting

During Development

• Read complete files before modification
• Check for existing patterns/imports
• Make minimal, targeted changes
• Test frequently (compilation/functionality)
• Use npm run type-check:watch for continuous feedback
• Ask questions when uncertain

Session End Protocol

• Ensure all code compiles successfully
• Run npm run check-all for final verification
• Create checkpoint with detailed description
• Update memories with current status
• Document any known issues or incomplete work

🏗️ ARCHITECTURE BEST PRACTICES

Code Organization

• Follow project's established patterns
• Use feature-based organization when possible
• Maintain consistent naming conventions
• Document architectural decisions

Import Management

• Group imports logically (external, internal, relative)
• Remove unused imports
• Avoid duplicate imports
• Use absolute imports when available

Error Handling

• Implement proper error boundaries
• Add meaningful error messages
• Log errors appropriately
• Fail gracefully when possible

🚑 EMERGENCY RECOVERY PROCEDURES

If Errors Multiply

1. STOP immediately - Don't make more changes
2. Restore last working checkpoint
3. Run npm run type-check to identify core issues
4. Fix core issues first before derivative problems
5. Test compilation before proceeding

If Session Goes Off Track

1. Restore last working checkpoint
2. Read complete problematic files
3. Understand actual vs assumed issues
4. Make minimal targeted fixes only
5. Test after each fix with npm run check-all

📊 SUCCESS METRICS

Green Flags (Healthy Session)

• ✅ Build/compilation succeeds consistently
• ✅ npm run check-all passes without errors
• ✅ No duplicate code or imports generated
• ✅ Targeted, minimal changes made
• ✅ User confirms functionality works
• ✅ Clear checkpoint created with working state

Red Flags (Stop and Reassess)

• 🚨 Compilation errors increasing instead of decreasing
• 🚨 TypeScript watch mode showing cascading errors
• 🚨 Adding multiple duplicates/assumptions
• 🚨 Making changes without understanding current structure
• 🚨 User expressing confusion about changes
• 🚨 Core functionality breaking unexpectedly

🎯 UNIVERSAL LESSONS LEARNED

Critical Insights

• Enhanced development scripts prevent 80% of development issues
• Type confusion is the root cause of AI coding issues
• Always run build/compilation FIRST - it's not optional
• Fix core definitions to eliminate cascade errors
• Reading complete files prevents duplicate code generation
• Small, targeted changes beat comprehensive modifications

Error Prevention Patterns

• Use type-check:watch for immediate feedback
• Establish and follow naming conventions
• Maintain type definitions separate from implementation
• Regular compilation checking prevents error accumulation
• User-driven verification works better than AI assumptions

Communication Patterns

• Ask specific questions rather than making assumptions
• Explain technical decisions briefly when relevant
• Warn about potential risks before making changes
• Suggest improvements for session efficiency

🔧 PROJECT-SPECIFIC CUSTOMIZATION AREAS

Tech Stack Adaptations

• Replace npm run build with your build command
• Adapt type checking for your language (TypeScript, Flow, etc.)
• Modify import patterns for your framework
• Adjust error handling for your platform

Development Environment

• Configure for your IDE/editor setup
• Adapt for your testing framework
• Modify for your deployment pipeline
• Adjust for your debugging tools

Team Standards

• Incorporate your coding standards
• Add your specific naming conventions
• Include your review processes
• Integrate your documentation requirements

💡 IMPLEMENTATION CHECKLIST

Initial Project Setup

• Copy and customize these instructions for your project
• Add enhanced development scripts to package.json
• Configure strict TypeScript settings
• Set up checkpoint strategy
• Create initial memory files documenting workflow

Session Preparation

• Ensure Serena has access to these instructions
• Test build/compilation commands work
• Verify npm run check-all passes
• Verify checkpoint system functions
• Train team on session start protocol

Ongoing Maintenance

• Update instructions based on project learnings
• Document new patterns discovered
• Refine emergency recovery procedures
• Share successful patterns across projects

🚀 DEVELOPMENT SCRIPT REFERENCE

Daily Development Commands

npm run dev                 # Start development server
npm run type-check:watch   # Continuous type checking (run in separate terminal)
npm run lint:fix           # Auto-fix style issues
npm run check-all          # Pre-commit verification

Why These Scripts are Essential

• type-check:watch: Provides immediate TypeScript feedback while coding
• check-all: Combines type-check + lint for comprehensive validation
• lint:fix: Maintains consistent code style automatically
• Enhanced tsconfig: Catches common bugs with stricter settings

---

🚀 FINAL REMINDERS

The Four Pillars of Successful AI Coding:

1. Enhanced Development Scripts - Professional tooling from session one
2. Compilation Discipline - Always verify build status
3. Read Before Write - Understand before modifying
4. Ask Before Assume - Clarify rather than guess

Remember: It's better to ask questions than make assumptions. Better to fix root causes than add duplicates. Better to stop and recover than continue breaking things.

This template evolved from real project experience and proven results. The enhanced development scripts have prevented countless development issues across multiple projects.

[MischaPanch]

Thank you for sharing! I'll consider using some of this in our recommendations in the readme

[riccorohl]

Quick question, where are the Serena initial instructions pulled from? I had a really weird interaction today while coding

[MischaPanch]

They're assemled from the active context and the modes, and a prompt in the project.yml (if you configured one). you can see all prompt templates in src/serena/resources/config. I also added a new command today print-system-prompt, which you can call as:

uvx --from git+https://github.com/oraios/serena print-system-prompt --only-instructions

to see the instructions for your project