Skip to content

Migrate project to Claude Code as primary AI coding assistant #1161

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hotlong merged 1 commit into from
Apr 16, 2026
+71 −10
Merged

Migrate project to Claude Code as primary AI coding assistant #1161

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ objectstack-ai/spec/
│ ├── app-crm/ # Advanced: full CRM with relations
│ └── plugin-bi/ # Plugin example: BI dashboard
│
├── skills/ # 🤖 AI skill definitions (for Copilot/Cursor)
├── skills/ # 🤖 AI skill definitions (for Claude Code, Copilot, Cursor)
Comment on lines 90 to +93
Copy link

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This monorepo structure block uses objectstack-ai/spec/ as the root, while CLAUDE.md uses objectstack-ai/framework/, and the actual repository root is neither. Since this section is meant to orient contributors, please align the root path across both instruction files (or switch to a root-agnostic label) to avoid confusion.

Copilot uses AI. Check for mistakes.
│ ├── objectstack-schema/
│ ├── objectstack-query/
│ ├── objectstack-api/
Expand Down
16 changes: 11 additions & 5 deletions .github/prompts/OVERVIEW.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,16 +114,22 @@ ObjectStack AI Prompts

## 🚀 使用方式 (Usage)

### GitHub Copilot 集成
### AI 编码助手集成

这些提示词会被 GitHub Copilot 自动加载：
这些提示词兼容多个 AI 编码助手：

- **Claude Code**（推荐）：从代码库上下文自动加载
- **GitHub Copilot**：在代码库中工作时自动加载
- **Cursor**：可引用这些提示词获取上下文感知帮助

提示词会根据以下内容自动加载：

Comment on lines +117 to 126
Copy link

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这里写“提示词会…自动加载/从代码库上下文自动加载”可能会让人误以为 .github/prompts/*.prompt.md 会被助手默认注入上下文。建议改成更精确的描述（例如：这些提示词文件可被选择/引用/调用以提供上下文），并说明不同助手的使用方式差异。

Copilot uses AI. Check for mistakes.
```
.github/
└── prompts/
├── data-protocol.prompt.md ← 编辑数据协议时自动加载
├── ui-protocol.prompt.md ← 编辑UI协议时自动加载
├── system-protocol.prompt.md ← 编辑系统协议时自动加载
├── data-protocol.prompt.md ← 编辑数据协议时加载
├── ui-protocol.prompt.md ← 编辑UI协议时加载
├── system-protocol.prompt.md ← 编辑系统协议时加载
└── ...
```

Expand Down
10 changes: 8 additions & 2 deletions .github/prompts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,9 +142,15 @@ These prompts help with specific development tasks:

## 🎯 How to Use These Prompts

### For GitHub Copilot
### For AI Coding Assistants

These prompts are automatically loaded by GitHub Copilot when working in the repository. They provide context-aware assistance based on:
These prompts are compatible with multiple AI coding assistants:

- **Claude Code** (Recommended): Automatically loaded from the repository context
- **GitHub Copilot**: Automatically loaded when working in the repository
- **Cursor**: Can reference these prompts for context-aware assistance
Comment on lines +149 to +151
Copy link

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text claims these prompt files are “Automatically loaded” by Claude Code/Copilot. Unless there is a specific integration that loads .github/prompts/*.prompt.md implicitly, this wording is likely to mislead—Claude Code is documented to auto-load CLAUDE.md, but prompt files typically need to be referenced/selected. Suggest rephrasing to describe the actual usage mechanism (e.g., “available as prompt files you can invoke/reference”).

Suggested change
- **Claude Code** (Recommended): Automatically loaded from the repository context
- **GitHub Copilot**: Automatically loaded when working in the repository
- **Cursor**: Can reference these prompts for context-aware assistance
- **Claude Code** (Recommended): Available as repository prompt files you can reference alongside the repo context
- **GitHub Copilot**: Available as prompt files you can open, reference, or adapt while working in the repository
- **Cursor**: Can reference these prompt files for context-aware assistance

Copilot uses AI. Check for mistakes.

They provide context-aware assistance based on:
- The file you're editing
- The protocol layer you're working on
- The task you're performing
Expand Down
53 changes: 51 additions & 2 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

> **Last synced with `.github/copilot-instructions.md`:** 2026-04-16
>
> This file is the **Claude Code** equivalent of `.github/copilot-instructions.md` (GitHub Copilot).
> This file is the **Claude Code** primary instruction file for ObjectStack development.
> A parallel `.github/copilot-instructions.md` exists for GitHub Copilot compatibility.
> Keep both files in sync when updating project-wide AI instructions.
Copy link

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The header still says “Keep both files in sync”, but this file now intentionally contains Claude Code–specific content (e.g., the “Claude Code Best Practices” section) that does not exist in .github/copilot-instructions.md. Consider clarifying what must stay synchronized (shared directives/structure) vs what is allowed to diverge (assistant-specific guidance), otherwise the “synced” note becomes misleading.

Suggested change
> Keep both files in sync when updating project-wide AI instructions.
> Keep shared project-wide directives, structure, and core architectural guidance synchronized between both files.
> Assistant-specific guidance may differ where needed for Claude Code or GitHub Copilot behavior.

Copilot uses AI. Check for mistakes.

---
Expand Down Expand Up @@ -88,7 +89,7 @@ objectstack-ai/framework/
│ └── server/ # 🚀 Production server (multi-app orchestration)
│
├── examples/ # 📚 Reference implementations
├── skills/ # 🤖 AI skill definitions (for Copilot/Cursor/Claude)
├── skills/ # 🤖 AI skill definitions (for Claude Code, Copilot, Cursor)
└── content/docs/ # 📝 Documentation content
Comment on lines 89 to 93
Copy link

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The monorepo structure diagram appears inconsistent with the rest of the repo and with .github/copilot-instructions.md (this file shows objectstack-ai/framework/, Copilot instructions show objectstack-ai/spec/, while the repository root here is neither). This can confuse readers; please align both diagrams to the actual repo layout or use a neutral root like objectstack-ai/.

Copilot uses AI. Check for mistakes.
```

Expand Down Expand Up @@ -264,6 +265,54 @@ When editing files matching these patterns, apply the corresponding architectura

---

## Claude Code Best Practices

This project is optimized for development with **Claude Code** (Anthropic's official AI coding assistant). Follow these practices for the best experience:

### Effective Prompting

1. **Be Specific**: Reference exact file paths and line numbers when discussing code
2. **Provide Context**: Mention the protocol domain you're working in (Data, UI, System, AI, API)
3. **Use Domain Skills**: Reference the appropriate skill file when working on specialized tasks
4. **Sequential Tasks**: Break complex tasks into smaller, testable increments

### Leveraging Claude Code Features

1. **Multi-File Awareness**: Claude Code can read and edit multiple files simultaneously
2. **Deep Analysis**: Request architectural analysis before making significant changes
3. **Code Review**: Ask for code review suggestions before committing
4. **Test-Driven**: Request test generation alongside implementation

### Working with This Repository

1. **Start with Skills**: Consult `skills/objectstack-{domain}/SKILL.md` for domain-specific guidance
2. **Check Prompts**: Review `.github/prompts/{domain}-protocol.prompt.md` for detailed context
3. **Follow Conventions**: Always adhere to Prime Directives (Zod-first, naming conventions, etc.)
4. **Incremental Changes**: Make small, focused changes and test frequently

### Example Prompts

**Data Protocol Work:**
```
"I need to add a new field type 'geolocation' to packages/spec/src/data/field-type.zod.ts.
First, read the existing field types to understand the pattern, then implement following
the Zod-first approach with proper TSDoc comments."
```

**Testing:**
```
"Review the test coverage for packages/spec/src/ui/view.zod.ts and suggest additional
edge cases we should test, particularly around view type validation."
```

**Architecture:**
```
"I want to add a new service for caching. Review packages/services/service-cache/ if it exists,
or suggest the architecture following the kernel-managed service pattern used in other services."
```

---

## Post-Task Checklist

After completing any task:
Expand Down
Loading