Skip to content

.copilot-init.md

Latest commit

 

History

History
168 lines (122 loc) · 4.24 KB

.copilot-init.md

File metadata and controls

168 lines (122 loc) · 4.24 KB

Copilot Initialization Guide

This document explains how to configure your Copilot, Claude, or other AI assistant for development on this project.

Quick Start

1. For GitHub Copilot Users

  • Recommended file: .github/copilot-instructions.md
  • Scope: Project-wide instruction file automatically loaded by Copilot
  • Content: Repository rules, current priorities, development guidance

2. For Claude Code / Web Interface

  • Reference file: CLAUDE.md
  • Content: Claude-specific priorities and editing guidelines
  • Setup: Paste content into system prompt or reference in conversation

3. For GLM / Other Models

  • Reference file: AGENTS.md
  • Content: Canonical OpenSpec workflow and project-specific rules
  • Bilingual: Also see AGENTS.zh-CN.md for Chinese-language guidance

Key Principles

1. OpenSpec-First Development

All changes flow through OpenSpec:

/opsx:propose → /opsx:apply → /opsx:archive

2. Read Specs Before Coding

Check openspec/specs/ for the definitive description of:

  • Capabilities and requirements
  • Supported scenarios and constraints
  • Architecture decisions

3. Minimize Context Overhead

  • Prefer /review for major architectural changes
  • Use long autopilot sessions instead of /fleet
  • Keep LSP/editor setup simple (clangd + compile_commands.json)

4. Documentation is Project-Specific

  • Remove or consolidate duplicate guidance
  • No generic boilerplate
  • Every file serves a clear purpose

File Reference

File Purpose Audience
.github/copilot-instructions.md Copilot-specific rules GitHub Copilot users
CLAUDE.md Claude-specific priorities Claude Code / Web
AGENTS.md OpenSpec workflow (English) All developers
AGENTS.zh-CN.md OpenSpec workflow (Chinese) Chinese-language developers
CONTRIBUTING.md Contributor workflow Open source contributors
openspec.yaml Capability registry OpenSpec framework

Environment Setup

LSP (Language Server Protocol)

Primary: clangd

cd /home/shane/dev/n-body
./scripts/build.sh Release
# compile_commands.json auto-generated at project root

Editor Setup:

  • VS Code: .vscode/settings.json (pre-configured)
  • Vim/Neovim: Use coc-clangd or similar
  • Other editors: Point to ${PROJECT}/compile_commands.json

Git Hooks

Optional but recommended:

./scripts/setup-hooks.sh
# Enables .githooks/pre-commit for format validation

Build Requirements

# Auto-detects CUDA; falls back to CPU-only if unavailable
./scripts/build.sh Release

# Force CPU-only
cmake -DNBODY_ENABLE_CUDA=OFF ..

Future Development Workflow

If this project needs further updates:

  1. Create a proposal:

    /opsx:propose "Description of change"

  2. Edit the generated artifacts:

    • proposal.md - Why the change
    • design.md - How to implement it
    • tasks.md - Implementation checklist

  3. Run implementation:

    /opsx:apply
# Follow task-by-task implementation
# Prefer one long autopilot session

  4. Archive when complete:

    /opsx:archive

Avoiding Common Pitfalls

❌ Don't:

  • Use /fleet for routine work (prefer longer single autopilot sessions)
  • Create parallel spec systems alongside openspec/
  • Add heavy plugins/MCPs without clear ROI
  • Let local branches diverge from main for extended periods

✅ Do:

  • Reference openspec/specs/ as the single source of truth
  • Use /review for architectural decisions
  • Keep AI instruction files aligned across all interfaces
  • Commit and merge frequently with clear messages

Documentation Navigation

  • Setup & Examples: See README.md or docs/setup/
  • Algorithms & Performance: See openspec/specs/simulation-core.md
  • Architecture: See docs/architecture/
  • Specifications: See openspec/specs/
  • Development: See AGENTS.md and CONTRIBUTING.md

Questions?

For questions about this project:

  1. Check the relevant OpenSpec spec in openspec/specs/
  2. Review documentation in docs/
  3. Search the GitHub repository
  4. Open an issue on GitHub

Last Updated: 2024-04-24 Version: 2.0.0 Status: Archive-ready