Compare commits
6 Commits
4cac53a41a
...
79ea2316e3
| Author | SHA1 | Date |
|---|---|---|
dzq
|
79ea2316e3 | |
|
dzq
|
ab2b30f907 | |
|
dzq
|
e16a4ccf1d | |
|
dzq
|
bf0a30e0ae | |
|
dzq
|
e2fffba3ca | |
|
dzq
|
ad3b46f185 |
|
|
@ -0,0 +1,34 @@
|
|||
# 编辑器和IDE
|
||||
# ============
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
.vs/
|
||||
*.suo
|
||||
*.user
|
||||
*.tmp
|
||||
|
||||
# 日志文件
|
||||
# ========
|
||||
*.log
|
||||
logs/
|
||||
|
||||
# 依赖目录（如使用工具管理依赖）
|
||||
# ==============================
|
||||
node_modules/
|
||||
vendor/
|
||||
|
||||
# 缓存文件
|
||||
# ========
|
||||
.cache/
|
||||
*.cache
|
||||
|
||||
# 编译输出（如适用）
|
||||
# ================
|
||||
dist/
|
||||
build/
|
||||
out/
|
||||
|
||||
.claude/
|
||||
268
CLAUDE.md
268
CLAUDE.md
|
|
@ -1,148 +1,143 @@
|
|||
# Claude Code 翻译项目指南
|
||||
# CLAUDE.md
|
||||
|
||||
## 项目概述
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
本项目是使用 Claude Code 协助进行的翻译项目，致力于提供高质量、准确、一致的翻译服务。
|
||||
## Project Overview
|
||||
|
||||
## 核心原则
|
||||
This is a **translation repository** for Claude Code documentation, focusing on translating English technical documentation into Chinese. The repository maintains source documents in `/source/` and their translated versions in `/translated/`.
|
||||
|
||||
### 1. 翻译质量标准
|
||||
- **准确性**：确保翻译内容忠实于原文，不添加、遗漏或曲解信息
|
||||
- **流畅性**：译文应符合目标语言的表达习惯，读起来自然流畅
|
||||
- **一致性**：全文使用统一的术语和表达方式
|
||||
- **语境适配**：根据目标受众调整语言风格和表达方式
|
||||
**Primary languages:**
|
||||
- Source: English
|
||||
- Target: Chinese (Simplified)
|
||||
|
||||
### 2. 术语管理
|
||||
- 建立并维护术语表，确保关键概念翻译的一致性
|
||||
- 对于新术语或不确定的翻译，需标记并寻求确认
|
||||
- 保留原文专有名词（如人名、地名）并在必要时提供音译
|
||||
- 技术术语需准确翻译，并考虑行业标准用法
|
||||
## Repository Structure
|
||||
|
||||
## 文件组织
|
||||
|
||||
### 目录结构
|
||||
```
|
||||
translation/
|
||||
├── CLAUDE.md # 本文件
|
||||
├── README.md # 项目说明
|
||||
├── glossary.md # 术语表
|
||||
├── source/ # 原文文件
|
||||
│ ├── documents/ # 文档原文
|
||||
│ └── assets/ # 图片、表格等资源
|
||||
├── translated/ # 翻译文件
|
||||
│ ├── documents/ # 翻译后的文档
|
||||
│ └── assets/ # 翻译后的资源
|
||||
├── references/ # 参考资料
|
||||
│ ├── style-guide.md # 风格指南
|
||||
│ └── resources/ # 翻译参考资料
|
||||
└── reviews/ # 审校记录
|
||||
├── review-001.md # 审校记录
|
||||
└── feedback.md # 反馈与改进
|
||||
├── source/ # Original English documents
|
||||
│ ├── documents/ # Markdown documentation
|
||||
│ │ ├── awesome-claude-code.md
|
||||
│ │ ├── claude-code-infrastructure-showcase/
|
||||
│ │ ├── newsminimalist/
|
||||
│ │ └── wirelesswire/
|
||||
│ └── assets/ # Images, SVGs, other resources
|
||||
├── translated/ # Chinese translations
|
||||
│ ├── documents/ # Translated markdown files
|
||||
│ │ ├── awesome-claude-code.md (translated)
|
||||
│ │ ├── claude-code-infrastructure-showcase/ (translated)
|
||||
│ │ └── ...
|
||||
│ └── assets/ # Translated resources
|
||||
├── references/ # Translation resources
|
||||
│ ├── glossary/ # Term glossary
|
||||
│ │ └── glossary.md # English-Chinese term pairs
|
||||
│ ├── style-guide.md # Translation style guidelines
|
||||
│ └── resources/ # Reference materials
|
||||
├── reviews/ # Review records
|
||||
│ ├── review-001.md # Translation review notes
|
||||
│ └── feedback.md # Feedback and improvements
|
||||
├── .claude/ # Claude Code configuration
|
||||
│ └── settings.local.json
|
||||
├── CLAUDE.md # This file
|
||||
└── README.md # Project description
|
||||
```
|
||||
|
||||
### 文件命名规范
|
||||
- 保持与原文相同的文件结构
|
||||
- 翻译文件添加语言标识（如 `doc_zh.md`）
|
||||
- 版本控制使用语义化版本号（v1.0, v1.1）
|
||||
## Key Documents
|
||||
|
||||
## 翻译流程
|
||||
### `/references/glossary/glossary.md`
|
||||
Maintains consistent terminology throughout translations. Always check here first when translating technical terms.
|
||||
|
||||
### 阶段1：准备工作
|
||||
1. 分析源文本，理解文档结构和风格
|
||||
2. 查阅相关术语表和参考资料
|
||||
3. 识别特殊要求（技术文档、法律文本、文学作品等）
|
||||
### `/references/style-guide.md`
|
||||
Defines translation style standards, tone, and language preferences for this project.
|
||||
|
||||
### 阶段2：初始翻译
|
||||
1. 逐段进行翻译，确保上下文连贯
|
||||
2. 标记疑问点或不明确之处
|
||||
3. 维护术语一致性
|
||||
### `/translated/[path]/[file].md` and `/source/[path]/[file].md`
|
||||
**Critical**: Always maintain the exact same directory structure and filename between source and translated documents. Only the language changes, not the structure.
|
||||
|
||||
### 阶段3：质量检查
|
||||
1. 全文校对，检查语法和拼写
|
||||
2. 对比原文确保无遗漏或误译
|
||||
3. 优化语言表达，提升流畅性
|
||||
## Translation Architecture
|
||||
|
||||
### 阶段4：审校
|
||||
1. 同行评议（如适用）
|
||||
2. 专家审校（如需要）
|
||||
3. 收集反馈并改进
|
||||
This repository uses a **simple directory mirroring** pattern:
|
||||
- Source files in `/source/` → Translated files in `/translated/`
|
||||
- One-to-one mapping: `/source/documents/a/b/c.md` → `/translated/documents/a/b/c.md`
|
||||
|
||||
## Claude Code 使用指南
|
||||
**No complex build tools or frameworks** - just Markdown files organized by language.
|
||||
|
||||
### 翻译指令模板
|
||||
## Translation Principles
|
||||
|
||||
#### 基本翻译
|
||||
```
|
||||
请将以下文本从 [源语言] 翻译为 [目标语言]：
|
||||
When working with translations:
|
||||
|
||||
[原文内容]
|
||||
1. **Accuracy**: Stay faithful to the original meaning
|
||||
2. **Fluency**: Use natural Chinese expressions
|
||||
3. **Consistency**: Use uniform terminology throughout
|
||||
4. **Context adaptation**: Adjust tone for Chinese technical readers
|
||||
5. **Format preservation**: All Markdown formatting, code blocks, links, and images must be preserved exactly
|
||||
|
||||
要求：
|
||||
- 保持原文格式
|
||||
- 确保术语一致性
|
||||
- 符合目标语言表达习惯
|
||||
```
|
||||
## Common Workflows
|
||||
|
||||
#### 带上下文的翻译
|
||||
```
|
||||
请在以下上下文中翻译该段落：
|
||||
### Translating a new document:
|
||||
1. Read the source document in `/source/documents/`
|
||||
2. Create translated version in `/translated/documents/` with same structure
|
||||
3. Reference `/references/glossary/glossary.md` for term consistency
|
||||
4. Update `/reviews/` with translation notes
|
||||
|
||||
原文：[段落内容]
|
||||
背景信息：[项目背景/术语解释]
|
||||
目标受众：[描述目标读者]
|
||||
风格要求：[正式/非正式/技术性等]
|
||||
```
|
||||
### Updating an existing translation:
|
||||
1. Compare source and translated files to identify changes
|
||||
2. Apply updates following the same translation principles
|
||||
3. Mark updated sections in review notes
|
||||
|
||||
#### 术语查询
|
||||
```
|
||||
请查询术语 "[术语]" 在以下领域的标准翻译：
|
||||
领域：[行业/学科]
|
||||
上下文：[使用场景]
|
||||
已有翻译：[如已翻译的版本]
|
||||
```
|
||||
### Finding term translations:
|
||||
- **Always check** `/references/glossary/glossary.md` before translating any technical term
|
||||
- Maintain consistency across all translated files
|
||||
- Add new terms to the glossary when encountered
|
||||
|
||||
### 常用指令
|
||||
## Development Tasks
|
||||
|
||||
1. **格式保持**
|
||||
```
|
||||
保持原文的 Markdown 格式、标题层级、列表结构
|
||||
```
|
||||
### No Build System Required
|
||||
This is a documentation project. Documents are plain Markdown files. There is no:
|
||||
- Build process
|
||||
- Test suite
|
||||
- Linting configuration
|
||||
- Compilation step
|
||||
|
||||
2. **术语查询**
|
||||
```
|
||||
请在 glossary.md 中查找术语 "[术语]" 的定义
|
||||
```
|
||||
Simply edit Markdown files directly.
|
||||
|
||||
3. **一致性检查**
|
||||
```
|
||||
请检查以下文本中的术语 "[术语]" 使用是否一致
|
||||
```
|
||||
### Adding new documents:
|
||||
- Place English source in `/source/documents/[category]/`
|
||||
- Create Chinese translation in `/translated/documents/[category]/`
|
||||
- Maintain identical directory structure
|
||||
- Update git history with descriptive commit messages
|
||||
|
||||
4. **风格调整**
|
||||
```
|
||||
将以下文本调整为 [风格描述] 的语言风格
|
||||
```
|
||||
### Updating translations:
|
||||
1. Read both source and translated files
|
||||
2. Identify changed sections in source
|
||||
3. Update corresponding sections in translation
|
||||
4. Verify formatting and links are preserved
|
||||
|
||||
## 质量控制
|
||||
## Important Workflow Notes
|
||||
|
||||
### 自我检查清单
|
||||
- [ ] 译文忠实于原文，无添加或删减
|
||||
- [ ] 术语使用一致，符合术语表标准
|
||||
- [ ] 语法正确，符合目标语言规范
|
||||
- [ ] 格式与原文保持一致
|
||||
- [ ] 专有名词处理正确
|
||||
- [ ] 标点符号使用恰当
|
||||
- [ ] 数字、日期、单位格式正确
|
||||
1. **Directory mirroring is sacred**: Never change the directory structure between source and translation
|
||||
2. **Terminology consistency**: Before translating any technical term, check the glossary
|
||||
3. **Format preservation**: Markdown tables, code blocks, links, and images must be preserved exactly
|
||||
4. **Review process**: Significant translations should be documented in `/reviews/`
|
||||
5. **Version control**: Use meaningful commit messages describing what was translated or updated
|
||||
|
||||
### 常见问题预防
|
||||
1. **文化差异**：注意文化背景的转换，避免直译导致的误解
|
||||
2. **语言风格**：根据文本类型调整正式程度
|
||||
3. **技术准确性**：技术术语需确保专业性
|
||||
4. **版面布局**：保持文档的可读性和美观性
|
||||
## Working with Claude Code
|
||||
|
||||
## 版本管理
|
||||
When assisting with this repository, Claude Code should:
|
||||
- Read source documents before creating translations
|
||||
- Always check the glossary before translating technical terms
|
||||
- Preserve all Markdown formatting
|
||||
- Maintain consistent terminology across all files
|
||||
- Document translation decisions when they're non-obvious
|
||||
|
||||
### 提交规范
|
||||
## Quick Reference
|
||||
|
||||
- **Translate new doc**: Copy structure from `/source/` → `/translated/`, maintain directory paths
|
||||
- **Find term translation**: Check `/references/glossary/glossary.md`
|
||||
- **Style questions**: Refer to `/references/style-guide.md`
|
||||
- **Document decisions**: Add notes to `/reviews/` when making significant translation choices
|
||||
|
||||
## Version Control
|
||||
|
||||
Commit message format:
|
||||
```
|
||||
[类型]: 简要描述
|
||||
|
||||
|
|
@ -156,47 +151,14 @@ translation/
|
|||
日期：[YYYY-MM-DD]
|
||||
```
|
||||
|
||||
### 变更类型
|
||||
- `feat`: 新增翻译内容
|
||||
- `fix`: 修正翻译错误
|
||||
- `update`: 更新现有翻译
|
||||
- `review`: 审校修改
|
||||
- `style`: 格式或样式调整
|
||||
|
||||
## 参考资源
|
||||
|
||||
### 工具推荐
|
||||
- 术语管理：维护 `glossary.md`
|
||||
- 格式检查：保持 Markdown 语法正确
|
||||
- 翻译记忆：记录常用短语和句式
|
||||
|
||||
### 学习资源
|
||||
- 目标语言官方语法指南
|
||||
- 专业领域翻译标准
|
||||
- 行业术语词典
|
||||
|
||||
## 协作指南
|
||||
|
||||
### 与 Claude Code 协作
|
||||
1. **明确指示**：清晰描述翻译要求和限制
|
||||
2. **提供上下文**：给出足够的背景信息
|
||||
3. **分段处理**：大文档建议分段翻译
|
||||
4. **及时反馈**：对不满意的部分提出修改建议
|
||||
|
||||
### 反馈机制
|
||||
- 记录遇到的问题和解决方案
|
||||
- 更新术语表和风格指南
|
||||
- 总结翻译经验和最佳实践
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **版权尊重**：仅翻译已授权的内容
|
||||
2. **保密性**：对敏感信息严格保密
|
||||
3. **持续改进**：根据反馈不断优化翻译质量
|
||||
4. **知识积累**：建立个人翻译知识库
|
||||
Change types:
|
||||
- `feat`: New translation content
|
||||
- `fix`: Correct translation errors
|
||||
- `update`: Update existing translations
|
||||
- `review`: Review modifications
|
||||
- `style`: Format or style adjustments
|
||||
|
||||
---
|
||||
|
||||
**联系方式**：[项目负责人]
|
||||
**更新日期**：2025-11-11
|
||||
**版本**：v1.0
|
||||
**Last Updated**: 2025-11-20
|
||||
**Purpose**: Guide Claude Code instances working with this translation repository
|
||||
|
|
|
|||
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
本文档记录项目中使用的专业术语及其翻译对照。
|
||||
|
||||
**文件路径**：`references/glossary/glossary.md`
|
||||
|
||||
## 使用说明
|
||||
|
||||
- **原文**: 源语言中的术语
|
||||
|
|
@ -37,4 +39,5 @@
|
|||
|
||||
## 更新记录
|
||||
|
||||
- v1.0 (2025-11-11): 创建初始术语表
|
||||
- v1.0 (2025-11-11): 创建初始术语表
|
||||
- v1.1 (2025-11-12): 将术语表移动到 `references/glossary/` 目录
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,51 @@
|
|||
# Dependencies
|
||||
node_modules/
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
pnpm-debug.log*
|
||||
|
||||
# Environment variables
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
config.ini
|
||||
sentry.ini
|
||||
|
||||
# Logs
|
||||
logs/
|
||||
*.log
|
||||
pm2-logs/
|
||||
|
||||
# Build outputs
|
||||
dist/
|
||||
build/
|
||||
*.tsbuildinfo
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Testing
|
||||
coverage/
|
||||
.nyc_output/
|
||||
|
||||
# Temporary files
|
||||
tmp/
|
||||
temp/
|
||||
*.tmp
|
||||
|
||||
# Database
|
||||
*.sqlite
|
||||
*.db
|
||||
|
||||
# Prisma
|
||||
.env
|
||||
prisma/.env
|
||||
|
|
@ -0,0 +1,883 @@
|
|||
# Claude Integration Guide
|
||||
|
||||
**FOR CLAUDE CODE:** When a user asks you to integrate components from this showcase repository into their project, follow these instructions carefully.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This repository is a **reference library** of Claude Code infrastructure components. Users will ask you to help integrate specific pieces into their projects. Your role is to:
|
||||
|
||||
1. **Ask clarifying questions** about their project structure
|
||||
2. **Copy the appropriate files**
|
||||
3. **Customize configurations** for their setup
|
||||
4. **Verify the integration** works correctly
|
||||
|
||||
**Key Principle:** ALWAYS ask before assuming project structure. What works for one project won't work for another.
|
||||
|
||||
---
|
||||
|
||||
## Tech Stack Compatibility Check
|
||||
|
||||
**CRITICAL:** Before integrating a skill, verify the user's tech stack matches the skill requirements.
|
||||
|
||||
### Frontend Skills
|
||||
|
||||
**frontend-dev-guidelines requires:**
|
||||
- React (18+)
|
||||
- MUI v7
|
||||
- TanStack Query
|
||||
- TanStack Router
|
||||
- TypeScript
|
||||
|
||||
**Before integrating, ask:**
|
||||
"Do you use React with MUI v7?"
|
||||
|
||||
**If NO:**
|
||||
```
|
||||
The frontend-dev-guidelines skill is designed specifically for React + MUI v7. I can:
|
||||
1. Help you create a similar skill adapted for [their stack] using this as a template
|
||||
2. Extract the framework-agnostic patterns (file organization, performance, etc.)
|
||||
3. Skip this skill if not relevant
|
||||
|
||||
Which would you prefer?
|
||||
```
|
||||
|
||||
### Backend Skills
|
||||
|
||||
**backend-dev-guidelines requires:**
|
||||
- Node.js/Express
|
||||
- TypeScript
|
||||
- Prisma ORM
|
||||
- Sentry
|
||||
|
||||
**Before integrating, ask:**
|
||||
"Do you use Node.js with Express and Prisma?"
|
||||
|
||||
**If NO:**
|
||||
```
|
||||
The backend-dev-guidelines skill is designed for Express/Prisma. I can:
|
||||
1. Help you create similar guidelines adapted for [their stack] using this as a template
|
||||
2. Extract the architecture patterns (layered architecture works for any framework)
|
||||
3. Skip this skill
|
||||
|
||||
Which would you prefer?
|
||||
```
|
||||
|
||||
### Skills That Are Tech-Agnostic
|
||||
|
||||
These work for ANY tech stack:
|
||||
- ✅ **skill-developer** - Meta-skill, no tech requirements
|
||||
- ✅ **route-tester** - Only requires JWT cookie auth (framework agnostic)
|
||||
- ✅ **error-tracking** - Sentry works with most stacks
|
||||
|
||||
---
|
||||
|
||||
## General Integration Pattern
|
||||
|
||||
When user says: **"Add [component] to my project"**
|
||||
|
||||
1. Identify component type (skill/hook/agent/command)
|
||||
2. **CHECK TECH STACK COMPATIBILITY** (for frontend/backend skills)
|
||||
3. Ask about their project structure
|
||||
4. Copy files OR adapt for their stack
|
||||
5. Customize for their setup
|
||||
6. Verify integration
|
||||
7. Provide next steps
|
||||
|
||||
---
|
||||
|
||||
## Integrating Skills
|
||||
|
||||
### Step-by-Step Process
|
||||
|
||||
**When user requests a skill** (e.g., "add backend-dev-guidelines"):
|
||||
|
||||
#### 1. Understand Their Project
|
||||
|
||||
**ASK THESE QUESTIONS:**
|
||||
- "What's your project structure? Single app, monorepo, or multi-service?"
|
||||
- "Where is your [backend/frontend] code located?"
|
||||
- "What frameworks/technologies do you use?"
|
||||
|
||||
#### 2. Copy the Skill
|
||||
|
||||
```bash
|
||||
cp -r /path/to/showcase/.claude/skills/[skill-name] \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/skills/
|
||||
```
|
||||
|
||||
#### 3. Handle skill-rules.json
|
||||
|
||||
**Check if it exists:**
|
||||
```bash
|
||||
ls $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json
|
||||
```
|
||||
|
||||
**If NO (doesn't exist):**
|
||||
- Copy the template from showcase
|
||||
- Remove skills user doesn't want
|
||||
- Customize for their project
|
||||
|
||||
**If YES (exists):**
|
||||
- Read their current skill-rules.json
|
||||
- Add the new skill entry
|
||||
- Merge carefully to avoid breaking existing skills
|
||||
|
||||
#### 4. Customize Path Patterns
|
||||
|
||||
**CRITICAL:** Update `pathPatterns` in skill-rules.json to match THEIR structure:
|
||||
|
||||
**Example - User has monorepo:**
|
||||
```json
|
||||
{
|
||||
"backend-dev-guidelines": {
|
||||
"fileTriggers": {
|
||||
"pathPatterns": [
|
||||
"packages/api/src/**/*.ts",
|
||||
"packages/server/src/**/*.ts",
|
||||
"apps/backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example - User has single backend:**
|
||||
```json
|
||||
{
|
||||
"backend-dev-guidelines": {
|
||||
"fileTriggers": {
|
||||
"pathPatterns": [
|
||||
"src/**/*.ts",
|
||||
"backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Safe Generic Patterns** (when unsure):
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"**/*.ts", // All TypeScript files
|
||||
"src/**/*.ts", // Common src directory
|
||||
"backend/**/*.ts" // Common backend directory
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. Verify Integration
|
||||
|
||||
```bash
|
||||
# Check skill was copied
|
||||
ls -la $CLAUDE_PROJECT_DIR/.claude/skills/[skill-name]
|
||||
|
||||
# Validate skill-rules.json syntax
|
||||
cat $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json | jq .
|
||||
```
|
||||
|
||||
**Tell user:** "Try editing a file in [their-backend-path] and the skill should activate."
|
||||
|
||||
---
|
||||
|
||||
### Skill-Specific Notes
|
||||
|
||||
#### backend-dev-guidelines
|
||||
- **Tech Requirements:** Node.js/Express, Prisma, TypeScript, Sentry
|
||||
- **Ask:** "Do you use Express with Prisma?" "Where's your backend code?"
|
||||
- **If different stack:** Offer to adapt using this as template
|
||||
- **Customize:** pathPatterns
|
||||
- **Example paths:** `api/`, `server/`, `backend/`, `services/*/src/`
|
||||
- **Adaptation tip:** Architecture patterns (Routes→Controllers→Services) transfer to most frameworks
|
||||
|
||||
#### frontend-dev-guidelines
|
||||
- **Tech Requirements:** React 18+, MUI v7, TanStack Query/Router, TypeScript
|
||||
- **Ask:** "Do you use React with MUI v7?" "Where's your frontend code?"
|
||||
- **If different stack:** Offer to create adapted version (Vue, Angular, etc.)
|
||||
- **Customize:** pathPatterns + all framework-specific examples
|
||||
- **Example paths:** `frontend/`, `client/`, `web/`, `apps/web/src/`
|
||||
- **Adaptation tip:** File organization and performance patterns transfer, component code doesn't
|
||||
|
||||
#### route-tester
|
||||
- **Tech Requirements:** JWT cookie-based authentication (framework agnostic)
|
||||
- **Ask:** "Do you use JWT cookie-based authentication?"
|
||||
- **If NO:** "This skill is designed for JWT cookies. Want me to adapt it for [their auth type] or skip it?"
|
||||
- **Customize:** Service URLs, auth patterns
|
||||
- **Works with:** Any backend framework using JWT cookies
|
||||
|
||||
#### error-tracking
|
||||
- **Tech Requirements:** Sentry (works with most backends)
|
||||
- **Ask:** "Do you use Sentry?" "Where's your backend code?"
|
||||
- **If NO Sentry:** "Want to use this as template for [their error tracking]?"
|
||||
- **Customize:** pathPatterns
|
||||
- **Adaptation tip:** Error tracking philosophy transfers to other tools (Rollbar, Bugsnag, etc.)
|
||||
|
||||
#### skill-developer
|
||||
- **Tech Requirements:** None!
|
||||
- **Copy as-is** - meta-skill, fully generic, teaches skill creation for ANY tech stack
|
||||
|
||||
---
|
||||
|
||||
## Adapting Skills for Different Tech Stacks
|
||||
|
||||
When user's tech stack differs from skill requirements, you have options:
|
||||
|
||||
### Option 1: Adapt Existing Skill (Recommended)
|
||||
|
||||
**When to use:** User wants similar guidelines but for different tech
|
||||
|
||||
**Process:**
|
||||
1. **Copy the skill as a starting point:**
|
||||
```bash
|
||||
cp -r showcase/.claude/skills/frontend-dev-guidelines \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/skills/vue-dev-guidelines
|
||||
```
|
||||
|
||||
2. **Identify what needs changing:**
|
||||
- Framework-specific code examples (React → Vue)
|
||||
- Library APIs (MUI → Vuetify/PrimeVue)
|
||||
- Import statements
|
||||
- Component patterns
|
||||
|
||||
3. **Keep what transfers:**
|
||||
- File organization principles
|
||||
- Performance optimization strategies
|
||||
- TypeScript standards
|
||||
- General best practices
|
||||
|
||||
4. **Replace examples systematically:**
|
||||
- Ask user for equivalent patterns in their stack
|
||||
- Update code examples to their framework
|
||||
- Keep the overall structure and sections
|
||||
|
||||
5. **Update skill name and triggers:**
|
||||
- Rename skill appropriately
|
||||
- Update skill-rules.json triggers for their stack
|
||||
- Test activation
|
||||
|
||||
**Example - Adapting frontend-dev-guidelines for Vue:**
|
||||
```
|
||||
I'll create vue-dev-guidelines based on the React skill structure:
|
||||
- Replace React.FC → Vue defineComponent
|
||||
- Replace useSuspenseQuery → Vue composables
|
||||
- Replace MUI components → [their component library]
|
||||
- Keep: File organization, performance patterns, TypeScript guidelines
|
||||
|
||||
This will take a few minutes. Sound good?
|
||||
```
|
||||
|
||||
### Option 2: Extract Framework-Agnostic Patterns
|
||||
|
||||
**When to use:** Stacks are very different, but core principles apply
|
||||
|
||||
**Process:**
|
||||
1. Read through the existing skill
|
||||
2. Identify framework-agnostic patterns:
|
||||
- Layered architecture (backend)
|
||||
- File organization strategies
|
||||
- Performance optimization principles
|
||||
- Testing strategies
|
||||
- Error handling philosophy
|
||||
|
||||
3. Create new skill with just those patterns
|
||||
4. User can add framework-specific examples later
|
||||
|
||||
**Example:**
|
||||
```
|
||||
The backend-dev-guidelines uses Express, but the layered architecture
|
||||
(Routes → Controllers → Services → Repositories) works for Django too.
|
||||
|
||||
I can create a skill with:
|
||||
- Layered architecture pattern
|
||||
- Separation of concerns principles
|
||||
- Error handling best practices
|
||||
- Testing strategies
|
||||
|
||||
Then you can add Django-specific examples as you establish patterns.
|
||||
```
|
||||
|
||||
### Option 3: Use as Reference Only
|
||||
|
||||
**When to use:** Too different to adapt, but user wants inspiration
|
||||
|
||||
**Process:**
|
||||
1. User browses the existing skill
|
||||
2. You help create a new skill from scratch
|
||||
3. Use existing skill's structure as a template
|
||||
4. Follow modular pattern (main + resource files)
|
||||
|
||||
### What Usually Transfers Across Tech Stacks
|
||||
|
||||
**Architecture & Organization:**
|
||||
- ✅ Layered architecture (Routes/Controllers/Services pattern)
|
||||
- ✅ Separation of concerns
|
||||
- ✅ File organization strategies (features/ pattern)
|
||||
- ✅ Progressive disclosure (main + resource files)
|
||||
- ✅ Repository pattern for data access
|
||||
|
||||
**Development Practices:**
|
||||
- ✅ Error handling philosophy
|
||||
- ✅ Input validation importance
|
||||
- ✅ Testing strategies
|
||||
- ✅ Performance optimization principles
|
||||
- ✅ TypeScript best practices
|
||||
|
||||
**Framework-Specific Code:**
|
||||
- ❌ React hooks → Don't transfer to Vue/Angular
|
||||
- ❌ MUI components → Different component libraries
|
||||
- ❌ Prisma queries → Different ORM syntax
|
||||
- ❌ Express middleware → Different framework patterns
|
||||
- ❌ Routing implementations → Framework-specific
|
||||
|
||||
### When to Recommend Adaptation vs Skipping
|
||||
|
||||
**Recommend adaptation if:**
|
||||
- User wants similar guidelines for their stack
|
||||
- Core patterns apply (layered architecture, etc.)
|
||||
- User has time to help with framework-specific examples
|
||||
|
||||
**Recommend skipping if:**
|
||||
- Stacks are completely different
|
||||
- User doesn't need those patterns
|
||||
- Would take too long to adapt
|
||||
- User prefers creating from scratch
|
||||
|
||||
---
|
||||
|
||||
## Integrating Hooks
|
||||
|
||||
### Essential Hooks (Always Safe to Copy)
|
||||
|
||||
#### skill-activation-prompt (UserPromptSubmit)
|
||||
|
||||
**Purpose:** Auto-suggests skills based on user prompts
|
||||
|
||||
**Integration (NO customization needed):**
|
||||
|
||||
```bash
|
||||
# Copy both files
|
||||
cp showcase/.claude/hooks/skill-activation-prompt.sh \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
cp showcase/.claude/hooks/skill-activation-prompt.ts \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
|
||||
# Make executable
|
||||
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh
|
||||
|
||||
# Install dependencies if needed
|
||||
if [ -f "showcase/.claude/hooks/package.json" ]; then
|
||||
cp showcase/.claude/hooks/package.json \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
cd $CLAUDE_PROJECT_DIR/.claude/hooks && npm install
|
||||
fi
|
||||
```
|
||||
|
||||
**Add to settings.json:**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**This hook is FULLY GENERIC** - works anywhere, no customization needed!
|
||||
|
||||
#### post-tool-use-tracker (PostToolUse)
|
||||
|
||||
**Purpose:** Tracks file changes for context management
|
||||
|
||||
**Integration (NO customization needed):**
|
||||
|
||||
```bash
|
||||
# Copy file
|
||||
cp showcase/.claude/hooks/post-tool-use-tracker.sh \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
|
||||
# Make executable
|
||||
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh
|
||||
```
|
||||
|
||||
**Add to settings.json:**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**This hook is FULLY GENERIC** - auto-detects project structure!
|
||||
|
||||
---
|
||||
|
||||
### Optional Hooks (Require Heavy Customization)
|
||||
|
||||
#### tsc-check.sh and trigger-build-resolver.sh (Stop hooks)
|
||||
|
||||
⚠️ **WARNING:** These hooks are configured for a specific multi-service monorepo structure.
|
||||
|
||||
**Before integrating, ask:**
|
||||
1. "Do you have a monorepo with multiple TypeScript services?"
|
||||
2. "What are your service directory names?"
|
||||
3. "Where are your tsconfig.json files located?"
|
||||
|
||||
**For SIMPLE projects (single service):**
|
||||
- **RECOMMEND SKIPPING** these hooks
|
||||
- They're overkill for single-service projects
|
||||
- User can run `tsc --noEmit` manually instead
|
||||
|
||||
**For COMPLEX projects (multi-service monorepo):**
|
||||
|
||||
1. Copy the files
|
||||
2. **MUST EDIT** tsc-check.sh - find this section:
|
||||
```bash
|
||||
case "$repo" in
|
||||
email|exports|form|frontend|projects|uploads|users|utilities|events|database)
|
||||
echo "$repo"
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
3. Replace with USER'S actual service names:
|
||||
```bash
|
||||
case "$repo" in
|
||||
api|web|auth|payments|notifications) # ← User's services
|
||||
echo "$repo"
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
4. Test manually before adding to settings.json:
|
||||
```bash
|
||||
./.claude/hooks/tsc-check.sh
|
||||
```
|
||||
|
||||
**IMPORTANT:** If this hook fails, it will block Stop events. Only add if you're sure it works for their setup.
|
||||
|
||||
---
|
||||
|
||||
## Integrating Agents
|
||||
|
||||
**Agents are STANDALONE** - easiest to integrate!
|
||||
|
||||
### Standard Agent Integration
|
||||
|
||||
```bash
|
||||
# Copy the agent file
|
||||
cp showcase/.claude/agents/[agent-name].md \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/agents/
|
||||
```
|
||||
|
||||
**That's it!** Agents work immediately, no configuration needed.
|
||||
|
||||
### Check for Hardcoded Paths
|
||||
|
||||
Some agents may reference paths. **Before copying, read the agent file and check for:**
|
||||
|
||||
- `~/git/old-project/` → Should be `$CLAUDE_PROJECT_DIR` or `.`
|
||||
- `/root/git/project/` → Should be `$CLAUDE_PROJECT_DIR` or `.`
|
||||
- Hardcoded screenshot paths → Ask user where they want screenshots
|
||||
|
||||
**If found, update them:**
|
||||
```bash
|
||||
sed -i 's|~/git/old-project/|.|g' $CLAUDE_PROJECT_DIR/.claude/agents/[agent].md
|
||||
sed -i 's|/root/git/.*PROJECT.*DIR|$CLAUDE_PROJECT_DIR|g' \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/agents/[agent].md
|
||||
```
|
||||
|
||||
### Agent-Specific Notes
|
||||
|
||||
**auth-route-tester / auth-route-debugger:**
|
||||
- Requires JWT cookie-based authentication in user's project
|
||||
- Ask: "Do you use JWT cookies for auth?"
|
||||
- If NO: "These agents are for JWT cookie auth. Skip them or want me to adapt?"
|
||||
|
||||
**frontend-error-fixer:**
|
||||
- May reference screenshot paths
|
||||
- Ask: "Where should screenshots be saved?"
|
||||
|
||||
**All other agents:**
|
||||
- Copy as-is, they're fully generic
|
||||
|
||||
---
|
||||
|
||||
## Integrating Slash Commands
|
||||
|
||||
```bash
|
||||
# Copy command file
|
||||
cp showcase/.claude/commands/[command].md \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/commands/
|
||||
```
|
||||
|
||||
### Customize Paths
|
||||
|
||||
Commands may reference dev docs paths. **Check and update:**
|
||||
|
||||
**dev-docs and dev-docs-update:**
|
||||
- Look for `dev/active/` path references
|
||||
- Ask: "Where do you want dev documentation stored?"
|
||||
- Update paths in the command files
|
||||
|
||||
**route-research-for-testing:**
|
||||
- May reference service paths
|
||||
- Ask about their API structure
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns & Best Practices
|
||||
|
||||
### Pattern: Asking About Project Structure
|
||||
|
||||
**DON'T assume:**
|
||||
- ❌ "I'll add this for your blog-api service"
|
||||
- ❌ "Configuring for your frontend directory"
|
||||
|
||||
**DO ask:**
|
||||
- ✅ "What's your project structure? Monorepo or single app?"
|
||||
- ✅ "Where is your backend code located?"
|
||||
- ✅ "Do you use workspaces or have multiple services?"
|
||||
|
||||
### Pattern: Customizing skill-rules.json
|
||||
|
||||
**User has monorepo with workspaces:**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"packages/*/src/**/*.ts",
|
||||
"apps/*/src/**/*.tsx"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**User has Nx monorepo:**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"apps/api/src/**/*.ts",
|
||||
"libs/*/src/**/*.ts"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**User has simple structure:**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"src/**/*.ts",
|
||||
"backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern: settings.json Integration
|
||||
|
||||
**NEVER copy the showcase settings.json directly!**
|
||||
|
||||
Instead, **extract and merge** the sections they need:
|
||||
|
||||
1. Read their existing settings.json
|
||||
2. Add the hook configurations they want
|
||||
3. Preserve their existing config
|
||||
|
||||
**Example merge:**
|
||||
```json
|
||||
{
|
||||
// ... their existing config ...
|
||||
"hooks": {
|
||||
// ... their existing hooks ...
|
||||
"UserPromptSubmit": [ // ← Add this section
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After integration, **verify these items:**
|
||||
|
||||
```bash
|
||||
# 1. Hooks are executable
|
||||
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh
|
||||
# Should show: -rwxr-xr-x
|
||||
|
||||
# 2. skill-rules.json is valid JSON
|
||||
cat $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json | jq .
|
||||
# Should parse without errors
|
||||
|
||||
# 3. Hook dependencies installed (if TypeScript hooks)
|
||||
ls $CLAUDE_PROJECT_DIR/.claude/hooks/node_modules/
|
||||
# Should show packages if package.json exists
|
||||
|
||||
# 4. Settings.json is valid JSON
|
||||
cat $CLAUDE_PROJECT_DIR/.claude/settings.json | jq .
|
||||
# Should parse without errors
|
||||
```
|
||||
|
||||
**Then ask user to test:**
|
||||
- "Try editing a file in [relevant-path] - the skill should activate"
|
||||
- "Try asking me a question about [topic] - I should suggest the skill"
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### ❌ DON'T: Copy settings.json as-is
|
||||
**Why:** The Stop hooks reference non-existent services
|
||||
**DO:** Extract only UserPromptSubmit and PostToolUse sections
|
||||
|
||||
### ❌ DON'T: Keep example service names
|
||||
**Why:** User doesn't have blog-api, auth-service, etc.
|
||||
**DO:** Ask about their actual structure and update
|
||||
|
||||
### ❌ DON'T: Skip making hooks executable
|
||||
**Why:** Hooks won't run without execute permission
|
||||
**DO:** Always `chmod +x` after copying
|
||||
|
||||
### ❌ DON'T: Assume monorepo structure
|
||||
**Why:** Most projects are single-service
|
||||
**DO:** Ask first, then customize
|
||||
|
||||
### ❌ DON'T: Add all skills at once
|
||||
**Why:** Overwhelming and may not all be relevant
|
||||
**DO:** Ask which skills are relevant to their work
|
||||
|
||||
### ❌ DON'T: Copy Stop hooks without testing
|
||||
**Why:** They can block the Stop event if they fail
|
||||
**DO:** Test manually first, only add if working
|
||||
|
||||
---
|
||||
|
||||
## Example Integration Conversations
|
||||
|
||||
### Example 1: Adding Backend Skill
|
||||
|
||||
**User:** "Add the backend-dev-guidelines skill to my project"
|
||||
|
||||
**Claude should respond:**
|
||||
```
|
||||
I'll add the backend-dev-guidelines skill. First, I need to understand
|
||||
your project structure:
|
||||
|
||||
1. Is this a monorepo with multiple services, or a single backend application?
|
||||
2. Where is your backend code located? (e.g., src/, backend/, server/)
|
||||
3. Do you use Express.js?
|
||||
```
|
||||
|
||||
**User:** "Single app, code is in src/api/, yes we use Express"
|
||||
|
||||
**Claude should:**
|
||||
1. Copy the skill directory
|
||||
2. Update skill-rules.json with pathPattern: `"src/api/**/*.ts"`
|
||||
3. Verify it's copied correctly
|
||||
4. Respond:
|
||||
```
|
||||
✅ Added backend-dev-guidelines skill!
|
||||
|
||||
Configuration:
|
||||
- Skill triggers when editing files in src/api/
|
||||
- Activated by keywords like "controller", "service", "route", "API"
|
||||
|
||||
Try it: Edit a file in src/api/ and you should see the skill suggestion.
|
||||
```
|
||||
|
||||
### Example 2: Setting Up Hooks
|
||||
|
||||
**User:** "Set up the skill activation hooks"
|
||||
|
||||
**Claude should respond:**
|
||||
```
|
||||
I'll set up the skill auto-activation system. This requires two hooks:
|
||||
1. skill-activation-prompt - Suggests skills based on your prompts
|
||||
2. post-tool-use-tracker - Tracks file changes
|
||||
|
||||
Do you have a .claude/settings.json file already, or should I create one?
|
||||
```
|
||||
|
||||
**User:** "I have settings.json already"
|
||||
|
||||
**Claude should:**
|
||||
1. Read their settings.json
|
||||
2. Copy both hook files
|
||||
3. Run npm install in hooks directory
|
||||
4. Add hook configurations to their settings.json (preserving existing config)
|
||||
5. Make hooks executable
|
||||
6. Respond:
|
||||
```
|
||||
✅ Skill activation hooks installed!
|
||||
|
||||
What I did:
|
||||
- Copied skill-activation-prompt hook
|
||||
- Copied post-tool-use-tracker hook
|
||||
- Installed dependencies
|
||||
- Added to your settings.json
|
||||
|
||||
Test it: Ask me "help with backend development" and I should suggest
|
||||
the backend-dev-guidelines skill.
|
||||
```
|
||||
|
||||
### Example 3: Adding Agent
|
||||
|
||||
**User:** "Add the code-architecture-reviewer agent"
|
||||
|
||||
**Claude should:**
|
||||
```
|
||||
The code-architecture-reviewer agent reviews code for architectural issues
|
||||
and best practices. This agent works standalone, no configuration needed.
|
||||
|
||||
I'll copy it to your .claude/agents/ directory now.
|
||||
```
|
||||
|
||||
**Then:**
|
||||
1. Copy the agent file
|
||||
2. Respond:
|
||||
```
|
||||
✅ Added code-architecture-reviewer agent!
|
||||
|
||||
Use it by running the Task tool with:
|
||||
- subagent_type: "code-architecture-reviewer"
|
||||
- prompt: Description of code to review
|
||||
|
||||
The agent will review your code and provide architectural feedback.
|
||||
```
|
||||
|
||||
### Example 3: Tech Stack Mismatch
|
||||
|
||||
**User:** "Add the frontend-dev-guidelines skill to my Vue project"
|
||||
|
||||
**Claude should:**
|
||||
```
|
||||
I see you're using Vue. The frontend-dev-guidelines skill is specifically
|
||||
designed for React + MUI v7. I have a few options:
|
||||
|
||||
Option 1 (Recommended): I can create a vue-dev-guidelines skill using the
|
||||
React skill as a template. I'll adapt:
|
||||
- Component patterns for Vue (Composition API, defineComponent)
|
||||
- Replace MUI examples with your component library
|
||||
- Adapt data fetching for Vue patterns
|
||||
- Keep: File organization, performance principles, TypeScript standards
|
||||
|
||||
Option 2: Extract only the framework-agnostic patterns (file organization,
|
||||
performance, testing) without React-specific code.
|
||||
|
||||
Option 3: Skip it and help you create Vue guidelines from scratch.
|
||||
|
||||
Which would you prefer?
|
||||
```
|
||||
|
||||
**User:** "Option 1 sounds good, I use Vuetify"
|
||||
|
||||
**Claude should:**
|
||||
1. Copy frontend-dev-guidelines as vue-dev-guidelines
|
||||
2. Go through each resource file
|
||||
3. Replace React patterns with Vue Composition API
|
||||
4. Replace MUI components with Vuetify
|
||||
5. Update skill-rules.json with Vue-specific triggers (.vue files)
|
||||
6. Respond:
|
||||
```
|
||||
✅ Created vue-dev-guidelines skill adapted for Vue 3 + Vuetify!
|
||||
|
||||
What I changed:
|
||||
- React.FC components → Vue defineComponent
|
||||
- MUI v7 examples → Vuetify components
|
||||
- TanStack Query → Your data fetching approach
|
||||
- File patterns → .vue files
|
||||
|
||||
What I kept:
|
||||
- File organization (features/ pattern)
|
||||
- Performance optimization strategies
|
||||
- TypeScript standards
|
||||
- Loading/error state principles
|
||||
|
||||
Try editing a .vue file - the skill should activate.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Tables
|
||||
|
||||
### What Needs Customization?
|
||||
|
||||
| Component | Tech Requirements | Customization | What to Ask |
|
||||
|-----------|------------------|--------------|-------------|
|
||||
| **skill-developer** | None | ✅ None | Copy as-is |
|
||||
| **backend-dev-guidelines** | Express/Prisma/Node | ⚠️ Paths + tech check | "Use Express/Prisma?" "Where's backend?" |
|
||||
| **frontend-dev-guidelines** | React/MUI v7 | ⚠️⚠️ Paths + framework | "Use React/MUI v7?" "Where's frontend?" |
|
||||
| **route-tester** | JWT cookies | ⚠️ Auth + paths | "JWT cookie auth?" |
|
||||
| **error-tracking** | Sentry | ⚠️ Paths | "Use Sentry?" "Where's backend?" |
|
||||
| **skill-activation-prompt** | ✅ None | Copy as-is |
|
||||
| **post-tool-use-tracker** | ✅ None | Copy as-is |
|
||||
| **tsc-check** | ⚠️⚠️⚠️ Heavy | "Monorepo or single service?" |
|
||||
| **All agents** | ✅ Minimal | Check paths |
|
||||
| **All commands** | ⚠️ Paths | "Where for dev docs?" |
|
||||
|
||||
### When to Recommend Skipping
|
||||
|
||||
| Component | Skip If... |
|
||||
|-----------|-----------|
|
||||
| **tsc-check hooks** | Single-service project or different build setup |
|
||||
| **route-tester** | Not using JWT cookie authentication |
|
||||
| **frontend-dev-guidelines** | Not using React + MUI |
|
||||
| **auth agents** | Not using JWT cookie auth |
|
||||
|
||||
---
|
||||
|
||||
## Final Tips for Claude
|
||||
|
||||
**When user says "add everything":**
|
||||
- Start with essentials: skill-activation hooks + 1-2 relevant skills
|
||||
- Don't overwhelm them with all 5 skills + 10 agents
|
||||
- Ask what they actually need
|
||||
|
||||
**When something doesn't work:**
|
||||
- Check verification checklist
|
||||
- Verify paths match their structure
|
||||
- Test hooks manually
|
||||
- Check for JSON syntax errors
|
||||
|
||||
**When user is unsure:**
|
||||
- Recommend starting with just skill-activation hooks
|
||||
- Add backend OR frontend skill (whichever they use)
|
||||
- Add more later as needed
|
||||
|
||||
**Always explain what you're doing:**
|
||||
- Show the commands you're running
|
||||
- Explain why you're asking questions
|
||||
- Provide clear next steps after integration
|
||||
|
||||
---
|
||||
|
||||
**Remember:** This is a reference library, not a working application. Your job is to help users cherry-pick and adapt components for THEIR specific project structure.
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2025 Claude Code Infrastructure Contributors
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
|
@ -0,0 +1,360 @@
|
|||
# Claude Code Infrastructure Showcase
|
||||
|
||||
**A curated reference library of production-tested Claude Code infrastructure.**
|
||||
|
||||
Born from 6 months of real-world use managing a complex TypeScript microservices project, this showcase provides the patterns and systems that solved the "skills don't activate automatically" problem and scaled Claude Code for enterprise development.
|
||||
|
||||
> **This is NOT a working application** - it's a reference library. Copy what you need into your own projects.
|
||||
|
||||
---
|
||||
|
||||
## What's Inside
|
||||
|
||||
**Production-tested infrastructure for:**
|
||||
- ✅ **Auto-activating skills** via hooks
|
||||
- ✅ **Modular skill pattern** (500-line rule with progressive disclosure)
|
||||
- ✅ **Specialized agents** for complex tasks
|
||||
- ✅ **Dev docs system** that survives context resets
|
||||
- ✅ **Comprehensive examples** using generic blog domain
|
||||
|
||||
**Time investment to build:** 6 months of iteration
|
||||
**Time to integrate into your project:** 15-30 minutes
|
||||
|
||||
---
|
||||
|
||||
## Quick Start - Pick Your Path
|
||||
|
||||
### 🤖 Using Claude Code to Integrate?
|
||||
|
||||
**Claude:** Read [`CLAUDE_INTEGRATION_GUIDE.md`](CLAUDE_INTEGRATION_GUIDE.md) for step-by-step integration instructions tailored for AI-assisted setup.
|
||||
|
||||
### 🎯 I want skill auto-activation
|
||||
|
||||
**The breakthrough feature:** Skills that actually activate when you need them.
|
||||
|
||||
**What you need:**
|
||||
1. The skill-activation hooks (2 files)
|
||||
2. A skill or two relevant to your work
|
||||
3. 15 minutes
|
||||
|
||||
**👉 [Setup Guide: .claude/hooks/README.md](.claude/hooks/README.md)**
|
||||
|
||||
### 📚 I want to add ONE skill
|
||||
|
||||
Browse the [skills catalog](.claude/skills/) and copy what you need.
|
||||
|
||||
**Available:**
|
||||
- **backend-dev-guidelines** - Node.js/Express/TypeScript patterns
|
||||
- **frontend-dev-guidelines** - React/TypeScript/MUI v7 patterns
|
||||
- **skill-developer** - Meta-skill for creating skills
|
||||
- **route-tester** - Test authenticated API routes
|
||||
- **error-tracking** - Sentry integration patterns
|
||||
|
||||
**👉 [Skills Guide: .claude/skills/README.md](.claude/skills/README.md)**
|
||||
|
||||
### 🤖 I want specialized agents
|
||||
|
||||
10 production-tested agents for complex tasks:
|
||||
- Code architecture review
|
||||
- Refactoring assistance
|
||||
- Documentation generation
|
||||
- Error debugging
|
||||
- And more...
|
||||
|
||||
**👉 [Agents Guide: .claude/agents/README.md](.claude/agents/README.md)**
|
||||
|
||||
---
|
||||
|
||||
## What Makes This Different?
|
||||
|
||||
### The Auto-Activation Breakthrough
|
||||
|
||||
**Problem:** Claude Code skills just sit there. You have to remember to use them.
|
||||
|
||||
**Solution:** UserPromptSubmit hook that:
|
||||
- Analyzes your prompts
|
||||
- Checks file context
|
||||
- Automatically suggests relevant skills
|
||||
- Works via `skill-rules.json` configuration
|
||||
|
||||
**Result:** Skills activate when you need them, not when you remember them.
|
||||
|
||||
### Production-Tested Patterns
|
||||
|
||||
These aren't theoretical examples - they're extracted from:
|
||||
- ✅ 6 microservices in production
|
||||
- ✅ 50,000+ lines of TypeScript
|
||||
- ✅ React frontend with complex data grids
|
||||
- ✅ Sophisticated workflow engine
|
||||
- ✅ 6 months of daily Claude Code use
|
||||
|
||||
The patterns work because they solved real problems.
|
||||
|
||||
### Modular Skills (500-Line Rule)
|
||||
|
||||
Large skills hit context limits. The solution:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
SKILL.md # <500 lines, high-level guide
|
||||
resources/
|
||||
topic-1.md # <500 lines each
|
||||
topic-2.md
|
||||
topic-3.md
|
||||
```
|
||||
|
||||
**Progressive disclosure:** Claude loads main skill first, loads resources only when needed.
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── skills/ # 5 production skills
|
||||
│ ├── backend-dev-guidelines/ (12 resource files)
|
||||
│ ├── frontend-dev-guidelines/ (11 resource files)
|
||||
│ ├── skill-developer/ (7 resource files)
|
||||
│ ├── route-tester/
|
||||
│ ├── error-tracking/
|
||||
│ └── skill-rules.json # Skill activation configuration
|
||||
├── hooks/ # 6 hooks for automation
|
||||
│ ├── skill-activation-prompt.* (ESSENTIAL)
|
||||
│ ├── post-tool-use-tracker.sh (ESSENTIAL)
|
||||
│ ├── tsc-check.sh (optional, needs customization)
|
||||
│ └── trigger-build-resolver.sh (optional)
|
||||
├── agents/ # 10 specialized agents
|
||||
│ ├── code-architecture-reviewer.md
|
||||
│ ├── refactor-planner.md
|
||||
│ ├── frontend-error-fixer.md
|
||||
│ └── ... 7 more
|
||||
└── commands/ # 3 slash commands
|
||||
├── dev-docs.md
|
||||
└── ...
|
||||
|
||||
dev/
|
||||
└── active/ # Dev docs pattern examples
|
||||
└── public-infrastructure-repo/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Catalog
|
||||
|
||||
### 🎨 Skills (5)
|
||||
|
||||
| Skill | Lines | Purpose | Best For |
|
||||
|-------|-------|---------|----------|
|
||||
| [**skill-developer**](.claude/skills/skill-developer/) | 426 | Creating and managing skills | Meta-development |
|
||||
| [**backend-dev-guidelines**](.claude/skills/backend-dev-guidelines/) | 304 | Express/Prisma/Sentry patterns | Backend APIs |
|
||||
| [**frontend-dev-guidelines**](.claude/skills/frontend-dev-guidelines/) | 398 | React/MUI v7/TypeScript | React frontends |
|
||||
| [**route-tester**](.claude/skills/route-tester/) | 389 | Testing authenticated routes | API testing |
|
||||
| [**error-tracking**](.claude/skills/error-tracking/) | ~250 | Sentry integration | Error monitoring |
|
||||
|
||||
**All skills follow the modular pattern** - main file + resource files for progressive disclosure.
|
||||
|
||||
**👉 [How to integrate skills →](.claude/skills/README.md)**
|
||||
|
||||
### 🪝 Hooks (6)
|
||||
|
||||
| Hook | Type | Essential? | Customization |
|
||||
|------|------|-----------|---------------|
|
||||
| skill-activation-prompt | UserPromptSubmit | ✅ YES | ✅ None needed |
|
||||
| post-tool-use-tracker | PostToolUse | ✅ YES | ✅ None needed |
|
||||
| tsc-check | Stop | ⚠️ Optional | ⚠️ Heavy - monorepo only |
|
||||
| trigger-build-resolver | Stop | ⚠️ Optional | ⚠️ Heavy - monorepo only |
|
||||
| error-handling-reminder | Stop | ⚠️ Optional | ⚠️ Moderate |
|
||||
| stop-build-check-enhanced | Stop | ⚠️ Optional | ⚠️ Moderate |
|
||||
|
||||
**Start with the two essential hooks** - they enable skill auto-activation and work out of the box.
|
||||
|
||||
**👉 [Hook setup guide →](.claude/hooks/README.md)**
|
||||
|
||||
### 🤖 Agents (10)
|
||||
|
||||
**Standalone - just copy and use!**
|
||||
|
||||
| Agent | Purpose |
|
||||
|-------|---------|
|
||||
| code-architecture-reviewer | Review code for architectural consistency |
|
||||
| code-refactor-master | Plan and execute refactoring |
|
||||
| documentation-architect | Generate comprehensive documentation |
|
||||
| frontend-error-fixer | Debug frontend errors |
|
||||
| plan-reviewer | Review development plans |
|
||||
| refactor-planner | Create refactoring strategies |
|
||||
| web-research-specialist | Research technical issues online |
|
||||
| auth-route-tester | Test authenticated endpoints |
|
||||
| auth-route-debugger | Debug auth issues |
|
||||
| auto-error-resolver | Auto-fix TypeScript errors |
|
||||
|
||||
**👉 [How agents work →](.claude/agents/README.md)**
|
||||
|
||||
### 💬 Slash Commands (3)
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| /dev-docs | Create structured dev documentation |
|
||||
| /dev-docs-update | Update docs before context reset |
|
||||
| /route-research-for-testing | Research route patterns for testing |
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Hooks + skill-rules.json = Auto-Activation
|
||||
|
||||
**The system:**
|
||||
1. **skill-activation-prompt hook** runs on every user prompt
|
||||
2. Checks **skill-rules.json** for trigger patterns
|
||||
3. Suggests relevant skills automatically
|
||||
4. Skills load only when needed
|
||||
|
||||
**This solves the #1 problem** with Claude Code skills: they don't activate on their own.
|
||||
|
||||
### Progressive Disclosure (500-Line Rule)
|
||||
|
||||
**Problem:** Large skills hit context limits
|
||||
|
||||
**Solution:** Modular structure
|
||||
- Main SKILL.md <500 lines (overview + navigation)
|
||||
- Resource files <500 lines each (deep dives)
|
||||
- Claude loads incrementally as needed
|
||||
|
||||
**Example:** backend-dev-guidelines has 12 resource files covering routing, controllers, services, repositories, testing, etc.
|
||||
|
||||
### Dev Docs Pattern
|
||||
|
||||
**Problem:** Context resets lose project context
|
||||
|
||||
**Solution:** Three-file structure
|
||||
- `[task]-plan.md` - Strategic plan
|
||||
- `[task]-context.md` - Key decisions and files
|
||||
- `[task]-tasks.md` - Checklist format
|
||||
|
||||
**Works with:** `/dev-docs` slash command to generate these automatically
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Important: What Won't Work As-Is
|
||||
|
||||
### settings.json
|
||||
The included `settings.json` is an **example only**:
|
||||
- Stop hooks reference specific monorepo structure
|
||||
- Service names (blog-api, etc.) are examples
|
||||
- MCP servers may not exist in your setup
|
||||
|
||||
**To use it:**
|
||||
1. Extract ONLY UserPromptSubmit and PostToolUse hooks
|
||||
2. Customize or skip Stop hooks
|
||||
3. Update MCP server list for your setup
|
||||
|
||||
### Blog Domain Examples
|
||||
Skills use generic blog examples (Post/Comment/User):
|
||||
- These are **teaching examples**, not requirements
|
||||
- Patterns work for any domain (e-commerce, SaaS, etc.)
|
||||
- Adapt the patterns to your business logic
|
||||
|
||||
### Hook Directory Structures
|
||||
Some hooks expect specific structures:
|
||||
- `tsc-check.sh` expects service directories
|
||||
- Customize based on YOUR project layout
|
||||
|
||||
---
|
||||
|
||||
## Integration Workflow
|
||||
|
||||
**Recommended approach:**
|
||||
|
||||
### Phase 1: Skill Activation (15 min)
|
||||
1. Copy skill-activation-prompt hook
|
||||
2. Copy post-tool-use-tracker hook
|
||||
3. Update settings.json
|
||||
4. Install hook dependencies
|
||||
|
||||
### Phase 2: Add First Skill (10 min)
|
||||
1. Pick ONE relevant skill
|
||||
2. Copy skill directory
|
||||
3. Create/update skill-rules.json
|
||||
4. Customize path patterns
|
||||
|
||||
### Phase 3: Test & Iterate (5 min)
|
||||
1. Edit a file - skill should activate
|
||||
2. Ask a question - skill should be suggested
|
||||
3. Add more skills as needed
|
||||
|
||||
### Phase 4: Optional Enhancements
|
||||
- Add agents you find useful
|
||||
- Add slash commands
|
||||
- Customize Stop hooks (advanced)
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
### For Users
|
||||
**Issues with integration?**
|
||||
1. Check [CLAUDE_INTEGRATION_GUIDE.md](CLAUDE_INTEGRATION_GUIDE.md)
|
||||
2. Ask Claude: "Why isn't [skill] activating?"
|
||||
3. Open an issue with your project structure
|
||||
|
||||
### For Claude Code
|
||||
When helping users integrate:
|
||||
1. **Read CLAUDE_INTEGRATION_GUIDE.md FIRST**
|
||||
2. Ask about their project structure
|
||||
3. Customize, don't blindly copy
|
||||
4. Verify after integration
|
||||
|
||||
---
|
||||
|
||||
## What This Solves
|
||||
|
||||
### Before This Infrastructure
|
||||
|
||||
❌ Skills don't activate automatically
|
||||
❌ Have to remember which skill to use
|
||||
❌ Large skills hit context limits
|
||||
❌ Context resets lose project knowledge
|
||||
❌ No consistency across development
|
||||
❌ Manual agent invocation every time
|
||||
|
||||
### After This Infrastructure
|
||||
|
||||
✅ Skills suggest themselves based on context
|
||||
✅ Hooks trigger skills at the right time
|
||||
✅ Modular skills stay under context limits
|
||||
✅ Dev docs preserve knowledge across resets
|
||||
✅ Consistent patterns via guardrails
|
||||
✅ Agents streamline complex tasks
|
||||
|
||||
---
|
||||
|
||||
## Community
|
||||
|
||||
**Found this useful?**
|
||||
|
||||
- ⭐ Star this repo
|
||||
- 🐛 Report issues or suggest improvements
|
||||
- 💬 Share your own skills/hooks/agents
|
||||
- 📝 Contribute examples from your domain
|
||||
|
||||
**Background:**
|
||||
This infrastructure was detailed in a post I made to Reddit ["Claude Code is a Beast – Tips from 6 Months of Hardcore Use"](https://www.reddit.com/r/ClaudeAI/comments/1oivjvm/claude_code_is_a_beast_tips_from_6_months_of/). After hundreds of requests, this showcase was created to help the community implement these patterns.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT License - Use freely in your projects, commercial or personal.
|
||||
|
||||
---
|
||||
|
||||
## Quick Links
|
||||
|
||||
- 📖 [Claude Integration Guide](CLAUDE_INTEGRATION_GUIDE.md) - For AI-assisted setup
|
||||
- 🎨 [Skills Documentation](.claude/skills/README.md)
|
||||
- 🪝 [Hooks Setup](.claude/hooks/README.md)
|
||||
- 🤖 [Agents Guide](.claude/agents/README.md)
|
||||
- 📝 [Dev Docs Pattern](dev/README.md)
|
||||
|
||||
**Start here:** Copy the two essential hooks, add one skill, and see the auto-activation magic happen.
|
||||
|
|
@ -0,0 +1,424 @@
|
|||
# Dev Docs Pattern
|
||||
|
||||
A methodology for maintaining project context across Claude Code sessions and context resets.
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
**Context resets lose everything:**
|
||||
- Implementation decisions
|
||||
- Key files and their purposes
|
||||
- Task progress
|
||||
- Technical constraints
|
||||
- Why certain approaches were chosen
|
||||
|
||||
**After a reset, Claude has to rediscover everything.**
|
||||
|
||||
---
|
||||
|
||||
## The Solution: Persistent Dev Docs
|
||||
|
||||
A three-file structure that captures everything needed to resume work:
|
||||
|
||||
```
|
||||
dev/active/[task-name]/
|
||||
├── [task-name]-plan.md # Strategic plan
|
||||
├── [task-name]-context.md # Key decisions & files
|
||||
└── [task-name]-tasks.md # Checklist format
|
||||
```
|
||||
|
||||
**These files survive context resets** - Claude reads them to get back up to speed instantly.
|
||||
|
||||
---
|
||||
|
||||
## Three-File Structure
|
||||
|
||||
### 1. [task-name]-plan.md
|
||||
|
||||
**Purpose:** Strategic plan for the implementation
|
||||
|
||||
**Contains:**
|
||||
- Executive summary
|
||||
- Current state analysis
|
||||
- Proposed future state
|
||||
- Implementation phases
|
||||
- Detailed tasks with acceptance criteria
|
||||
- Risk assessment
|
||||
- Success metrics
|
||||
- Timeline estimates
|
||||
|
||||
**When to create:** At the start of a complex task
|
||||
|
||||
**When to update:** When scope changes or new phases discovered
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
# Feature Name - Implementation Plan
|
||||
|
||||
## Executive Summary
|
||||
What we're building and why
|
||||
|
||||
## Current State
|
||||
Where we are now
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: Infrastructure (2 hours)
|
||||
- Task 1.1: Set up database schema
|
||||
- Acceptance: Schema compiles, relationships correct
|
||||
- Task 1.2: Create service structure
|
||||
- Acceptance: All directories created
|
||||
|
||||
### Phase 2: Core Functionality (3 hours)
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. [task-name]-context.md
|
||||
|
||||
**Purpose:** Key information for resuming work
|
||||
|
||||
**Contains:**
|
||||
- SESSION PROGRESS section (updated frequently!)
|
||||
- What's completed vs in-progress
|
||||
- Key files and their purposes
|
||||
- Important decisions made
|
||||
- Technical constraints discovered
|
||||
- Links to related files
|
||||
- Quick resume instructions
|
||||
|
||||
**When to create:** Start of task
|
||||
|
||||
**When to update:** **FREQUENTLY** - after major decisions, completions, or discoveries
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
# Feature Name - Context
|
||||
|
||||
## SESSION PROGRESS (2025-10-29)
|
||||
|
||||
### ✅ COMPLETED
|
||||
- Database schema created (User, Post, Comment models)
|
||||
- PostController implemented with BaseController pattern
|
||||
- Sentry integration working
|
||||
|
||||
### 🟡 IN PROGRESS
|
||||
- Creating PostService with business logic
|
||||
- File: src/services/postService.ts
|
||||
|
||||
### ⚠️ BLOCKERS
|
||||
- Need to decide on caching strategy
|
||||
|
||||
## Key Files
|
||||
|
||||
**src/controllers/PostController.ts**
|
||||
- Extends BaseController
|
||||
- Handles HTTP requests for posts
|
||||
- Delegates to PostService
|
||||
|
||||
**src/services/postService.ts** (IN PROGRESS)
|
||||
- Business logic for post operations
|
||||
- Next: Add caching
|
||||
|
||||
## Quick Resume
|
||||
To continue:
|
||||
1. Read this file
|
||||
2. Continue implementing PostService.createPost()
|
||||
3. See tasks file for remaining work
|
||||
```
|
||||
|
||||
**CRITICAL:** Update the SESSION PROGRESS section every time significant work is done!
|
||||
|
||||
---
|
||||
|
||||
### 3. [task-name]-tasks.md
|
||||
|
||||
**Purpose:** Checklist for tracking progress
|
||||
|
||||
**Contains:**
|
||||
- Phases broken down by logical sections
|
||||
- Tasks in checkbox format
|
||||
- Status indicators (✅/🟡/⏳)
|
||||
- Acceptance criteria
|
||||
- Quick resume section
|
||||
|
||||
**When to create:** Start of task
|
||||
|
||||
**When to update:** After completing each task or discovering new tasks
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
# Feature Name - Task Checklist
|
||||
|
||||
## Phase 1: Setup ✅ COMPLETE
|
||||
- [x] Create database schema
|
||||
- [x] Set up controllers
|
||||
- [x] Configure Sentry
|
||||
|
||||
## Phase 2: Implementation 🟡 IN PROGRESS
|
||||
- [x] Create PostController
|
||||
- [ ] Create PostService (IN PROGRESS)
|
||||
- [ ] Create PostRepository
|
||||
- [ ] Add validation with Zod
|
||||
|
||||
## Phase 3: Testing ⏳ NOT STARTED
|
||||
- [ ] Unit tests for service
|
||||
- [ ] Integration tests
|
||||
- [ ] Manual API testing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use Dev Docs
|
||||
|
||||
**Use for:**
|
||||
- ✅ Complex multi-day tasks
|
||||
- ✅ Features with many moving parts
|
||||
- ✅ Tasks likely to span multiple sessions
|
||||
- ✅ Work that needs careful planning
|
||||
- ✅ Refactoring large systems
|
||||
|
||||
**Skip for:**
|
||||
- ❌ Simple bug fixes
|
||||
- ❌ Single-file changes
|
||||
- ❌ Quick updates
|
||||
- ❌ Trivial modifications
|
||||
|
||||
**Rule of thumb:** If it takes more than 2 hours or spans multiple sessions, use dev docs.
|
||||
|
||||
---
|
||||
|
||||
## Workflow with Dev Docs
|
||||
|
||||
### Starting a New Task
|
||||
|
||||
1. **Use /dev-docs slash command:**
|
||||
```
|
||||
/dev-docs refactor authentication system
|
||||
```
|
||||
|
||||
2. **Claude creates the three files:**
|
||||
- Analyzes requirements
|
||||
- Examines codebase
|
||||
- Creates comprehensive plan
|
||||
- Generates context and tasks files
|
||||
|
||||
3. **Review and adjust:**
|
||||
- Check if plan makes sense
|
||||
- Add any missing considerations
|
||||
- Adjust timeline estimates
|
||||
|
||||
### During Implementation
|
||||
|
||||
1. **Refer to plan** for overall strategy
|
||||
2. **Update context.md** frequently:
|
||||
- Mark completed work
|
||||
- Note decisions made
|
||||
- Add blockers
|
||||
3. **Check off tasks** in tasks.md as you complete them
|
||||
|
||||
### After Context Reset
|
||||
|
||||
1. **Claude reads all three files**
|
||||
2. **Understands complete state** in seconds
|
||||
3. **Resumes exactly where you left off**
|
||||
|
||||
No need to explain what you were doing - it's all documented!
|
||||
|
||||
---
|
||||
|
||||
## Integration with Slash Commands
|
||||
|
||||
### /dev-docs
|
||||
**Creates:** New dev docs for a task
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/dev-docs implement real-time notifications
|
||||
```
|
||||
|
||||
**Generates:**
|
||||
- `dev/active/implement-real-time-notifications/`
|
||||
- implement-real-time-notifications-plan.md
|
||||
- implement-real-time-notifications-context.md
|
||||
- implement-real-time-notifications-tasks.md
|
||||
|
||||
### /dev-docs-update
|
||||
**Updates:** Existing dev docs before context reset
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/dev-docs-update
|
||||
```
|
||||
|
||||
**Updates:**
|
||||
- Marks completed tasks
|
||||
- Adds new tasks discovered
|
||||
- Updates context with session progress
|
||||
- Captures current state
|
||||
|
||||
**Use when:** Approaching context limits or ending session
|
||||
|
||||
---
|
||||
|
||||
## File Organization
|
||||
|
||||
```
|
||||
dev/
|
||||
├── README.md # This file
|
||||
├── active/ # Current work
|
||||
│ ├── task-1/
|
||||
│ │ ├── task-1-plan.md
|
||||
│ │ ├── task-1-context.md
|
||||
│ │ └── task-1-tasks.md
|
||||
│ └── task-2/
|
||||
│ └── ...
|
||||
└── archive/ # Completed work (optional)
|
||||
└── old-task/
|
||||
└── ...
|
||||
```
|
||||
|
||||
**active/**: Work in progress
|
||||
**archive/**: Completed tasks (for reference)
|
||||
|
||||
---
|
||||
|
||||
## Example: Real Usage
|
||||
|
||||
See **dev/active/public-infrastructure-repo/** in this repository for a real example:
|
||||
- **plan.md** - 700+ line strategic plan for creating this showcase
|
||||
- **context.md** - Tracks what's completed, decisions made, what's next
|
||||
- **tasks.md** - Checklist of all phases and tasks
|
||||
|
||||
This is the actual dev docs used to build this showcase!
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Update Context Frequently
|
||||
|
||||
**Bad:** Update only at end of session
|
||||
**Good:** Update after each major milestone
|
||||
|
||||
**SESSION PROGRESS section should always reflect reality:**
|
||||
```markdown
|
||||
## SESSION PROGRESS (YYYY-MM-DD)
|
||||
|
||||
### ✅ COMPLETED (list everything done)
|
||||
### 🟡 IN PROGRESS (what you're working on RIGHT NOW)
|
||||
### ⚠️ BLOCKERS (what's preventing progress)
|
||||
```
|
||||
|
||||
### Make Tasks Actionable
|
||||
|
||||
**Bad:** "Fix the authentication"
|
||||
**Good:** "Implement JWT token validation in AuthMiddleware.ts (Acceptance: Tokens validated, errors to Sentry)"
|
||||
|
||||
**Include:**
|
||||
- Specific file names
|
||||
- Clear acceptance criteria
|
||||
- Dependencies on other tasks
|
||||
|
||||
### Keep Plan Current
|
||||
|
||||
If scope changes:
|
||||
- Update the plan
|
||||
- Add new phases
|
||||
- Adjust timeline estimates
|
||||
- Note why scope changed
|
||||
|
||||
---
|
||||
|
||||
## For Claude Code
|
||||
|
||||
**When user asks to create dev docs:**
|
||||
|
||||
1. **Use the /dev-docs slash command** if available
|
||||
2. **Or create manually:**
|
||||
- Ask about the task scope
|
||||
- Analyze relevant codebase files
|
||||
- Create comprehensive plan
|
||||
- Generate context and tasks
|
||||
|
||||
3. **Structure the plan with:**
|
||||
- Clear phases
|
||||
- Actionable tasks
|
||||
- Acceptance criteria
|
||||
- Risk assessment
|
||||
|
||||
4. **Make context file resumable:**
|
||||
- SESSION PROGRESS at top
|
||||
- Quick resume instructions
|
||||
- Key files list with explanations
|
||||
|
||||
**When resuming from dev docs:**
|
||||
|
||||
1. **Read all three files** (plan, context, tasks)
|
||||
2. **Start with context.md** - has current state
|
||||
3. **Check tasks.md** - see what's done and what's next
|
||||
4. **Refer to plan.md** - understand overall strategy
|
||||
|
||||
**Update frequently:**
|
||||
- Mark tasks complete immediately
|
||||
- Update SESSION PROGRESS after significant work
|
||||
- Add new tasks as discovered
|
||||
|
||||
---
|
||||
|
||||
## Creating Dev Docs Manually
|
||||
|
||||
If you don't have the /dev-docs command:
|
||||
|
||||
**1. Create directory:**
|
||||
```bash
|
||||
mkdir -p dev/active/your-task-name
|
||||
```
|
||||
|
||||
**2. Create plan.md:**
|
||||
- Executive summary
|
||||
- Implementation phases
|
||||
- Detailed tasks
|
||||
- Timeline estimates
|
||||
|
||||
**3. Create context.md:**
|
||||
- SESSION PROGRESS section
|
||||
- Key files
|
||||
- Important decisions
|
||||
- Quick resume instructions
|
||||
|
||||
**4. Create tasks.md:**
|
||||
- Phases with checkboxes
|
||||
- [ ] Task format
|
||||
- Acceptance criteria
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
**Before dev docs:**
|
||||
- Context reset = start over
|
||||
- Forget why decisions were made
|
||||
- Lose track of progress
|
||||
- Repeat work
|
||||
|
||||
**After dev docs:**
|
||||
- Context reset = read 3 files, resume instantly
|
||||
- Decisions documented
|
||||
- Progress tracked
|
||||
- No repeated work
|
||||
|
||||
**Time saved:** Hours per context reset
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Try the pattern** on your next complex task
|
||||
2. **Use /dev-docs** slash command (if available)
|
||||
3. **Update frequently** - especially context.md
|
||||
4. **See it in action** - Browse dev/active/public-infrastructure-repo/
|
||||
|
||||
**Questions?** See [CLAUDE_INTEGRATION_GUIDE.md](../CLAUDE_INTEGRATION_GUIDE.md)
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
Doctors perform brain surgery 6400km away + 9 more stories
|
||||
|
||||
2025/11/12 00:37:07
|
||||
|
||||
In the last 4 days ChatGPT read 126822 top news stories. After removing previously covered events, there are 10 articles with a significance score over 5.5.
|
||||
|
||||
|
||||
[5.6] Surgeons remotely control robot to remove brain blood clot — bbc.com (+6)
|
||||
|
||||
For the first time, surgeons performed a trans-Atlantic robotic thrombectomy, removing a brain blood clot from a cadaver 6,400 kilometers away in a major medical breakthrough.
|
||||
|
||||
A neurosurgeon in Florida remotely controlled the robot in Scotland, experiencing minimal time lag. The technology aims to overcome specialist shortages and provide urgent stroke care to patients in remote locations, where treatment time is critical.
|
||||
|
||||
[5.9] China exempts Nexperia chips from export controls, easing fears for European car production — bbc.com (+17)
|
||||
|
||||
China has lifted export controls on Nexperia computer chips, averting feared production shutdowns at European car plants that rely on the components.
|
||||
|
||||
The decision reverses a block China imposed after the Dutch government took control of the Netherlands-based, Chinese-owned company in October. Automakers had warned their chip supplies were running out.
|
||||
|
||||
Though Nexperia is Dutch-based, many of its chips are finished in China before re-export. Officials are now working on a stable framework to ensure the full restoration of semiconductor flows.
|
||||
|
||||
Highly covered news with significance over 5.5
|
||||
|
||||
[6.4] Syrian President visits White House, discusses joining US-led coalition — ici.radio-canada.ca (French) (+116)
|
||||
|
||||
[5.5] US Senate passes deal to end government shutdown — bbc.com (+351)
|
||||
|
||||
[5.7] US takes over Gaza aid management from Israel — ilmessaggero.it (Italian) (+2)
|
||||
|
||||
[5.9] OpenAI faces seven lawsuits alleging ChatGPT caused user suicides and delusions — capitalgazette.com (+19)
|
||||
|
||||
[5.8] Munich court rules ChatGPT cannot use song lyrics without a license — tagesschau.de (German) (+9)
|
||||
|
||||
[6.1] Hong Kong scientists develop high-speed imaging for live brain cell activity in awake mice — medicalxpress.com (+2)
|
||||
|
||||
[5.5] Trinity College researchers develop whooping cough vaccine that stops transmission — irishexaminer.com (+3)
|
||||
|
||||
[6.0] CRISPR gene-editing therapy safely reduces cholesterol and triglycerides in first-in-human trial — newsroom.heart.org (+26)
|
||||
|
||||
Thanks for reading!
|
||||
|
||||
— Vadim
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
雑誌の入れ換えの無意味の時代
|
||||
前回に続いて引き続き1994年に刊行された橋本治の『浮上せよと活字は言う』を読んでいく。この本は橋本治による書物論であり、出版論である。なかでも1970年代後半以後、決定的に大きな変貌を遂げた雑誌について論じることに多くの紙幅が費されている。
|
||||
|
||||
よく知られるように、1980年代は「雑誌の時代」と呼ばれた。しかしこの時代には多くの雑誌が生まれただけでなく、休廃刊する雑誌も多かった。意味を失った古い雑誌が消え、新しい意味を担った雑誌が次々に生まれたのであればよいが、この時代に創刊された雑誌の多くも、読者の支持を安定して得ることができず早々に消えていった。こうした事情について橋本は次のように述べている。
|
||||
|
||||
「正確な言い方をすれば、一九八〇年代は「雑誌の時代」ではない。一九八〇年代は「雑誌の入れ換えの時代」であり、「雑誌の入れ換えの無意味の時代」だった。新雑誌の創刊点数の多さと、休廃刊された雑誌の数の多さが、そのことを証明している。一九八〇年代に、雑誌というものは変わってしまい、変わることにかなりの程度、失敗したのだ。」（「愚蒙を排す」）
|
||||
1970年代後半以後は総合雑誌（橋本のこの文章が連載された『中央公論』自身のような）が象徴していた権威ある「活字」が意味を失い、読者の支持を失っていく時代だった。そうしたなかで新たに創刊され、例外的に継続的かつ大規模な成功を収めた雑誌が二つある。『POPEYE』（マガジンハウス、1976年創刊）と『JJ』（光文社、1975年創刊）である。橋本は『浮上せよと活字は言う』の大半を、この二つの雑誌が出版界にもたらした変化の意味について論じることに費やす。その熱量がいま読むと不思議なほどに。
|
||||
|
||||
「古い分類」では「新しい意味」はすくえない
|
||||
二つの雑誌の具体的な特徴を論じる前に、橋本はまず、当時の出版業界がどのように雑誌を分類していたかに目を向ける。『POPEYE』と『JJ』はいずれも「ファッション誌」と呼ぶのがふさわしい内実を供えた雑誌だ。しかし1980年当時の出版業界の「雑誌統計分析」には「ファッション誌」という独立した部門がなかった。橋本が引用するところによると、雑誌は当時以下の25の部門に分けられていた。
|
||||
|
||||
児童・婦人・大衆・総合・文芸・芸能・美術・音楽・生活・趣味・スポーツ・経済・社会・時局・哲学・学参（学習参考書）・語学・教育・地歴・法律・科学・工学・医学・農水・週刊誌
|
||||
|
||||
この分類を橋本は「役所のセクションと大学の学部一覧に”週刊誌”という不思議なものがくっついている」と評するが、言い得て妙である。たとえば、この一覧には「婦人」はあっても「女性（誌）」や「ファッション（誌）」という区分がない。（ちなみに現在、日本雑誌協会ではこのように雑誌のジャンルを分類している。「多様化」といえばいえるが、分類基準の混乱はむしろ増しているように思える）
|
||||
|
||||
「一九七〇年代の後半から新雑誌の創刊ラッシュを迎える出版界は、まず、自分達がこういう不思議な分類項目の下で世界を把握して来たことの古さを考えるべきだったのだ。この考え方が古いから、新雑誌というものが登場しなければならなかったのだし、「雑誌の時代」という形で、雑誌＝”大衆的なるもの”にスポットが当てられなければならなかったのだ。」（同前）
|
||||
|
||||
そのように考える橋本にとって、『POPEYE』と『JJ』はまさにこの時代の「大衆的なるもの」を体現した雑誌だった。
|
||||
|
||||
では、なぜこれら二つの雑誌は画期的だったのか。橋本によれば『POPEYE』は「活字の意味を放逐する」という役割を果たし、『JJ』は「社会から規律を放逐する」という役割を果たした。両者の共通点は「見事に読者の声を反映させた」こと、「そしてそのことによって、編集権を放棄するというような離れ業までやって見せた」（「断絶を論ず」）ことにある。二つの雑誌は「ファッション」というかたちで当時の「現実」を体現し、それを知らない「知性」はその現実に敗北したのだ――橋本はそう断じた。
|
||||
|
||||
コラム化した「活字」は主役から降りた
|
||||
これらの雑誌が「活字」にもたらした最大の変化は、すべての文章のコラム化である。日本の出版業界でいわれる「コラム」は、columnが本来もつ「論説」というニュアンスを失った「短文の囲み記事」のことだ。
|
||||
|
||||
『POPEYE』や『JJ』以後、より正確には『an・an』以後に登場したビジュアル中心の「見る雑誌」では、グラフィックデザイナーがあらかじめ誌面を緻密に構成し、いわゆる「先割り」でレイアウトを行う。そこでは「活字」は雑誌を成り立たせる主役の座を追われ、決められた文字数のマスを埋める「部品（パーツ）」に過ぎなくなった。同じく和製英語の「ライター」とは、雑誌における部品としてのテキストを発注される納入業者のことである。
|
||||
|
||||
とはいえ、橋本はそのようにデザインやグラフィックに対して言葉（活字）が従属的な地位に追いやられたこと自体を、直ちに批判しているわけではない。橋本自身、作家デビュー以前はイラストレーターであり、少女マンガをはじめとするビジュアル表現のうちに新しい意味と希望を読み取った書き手だった。そして橋本自身、当時生まれたさまざまな「新雑誌」に幾多の「コラム」を書いた（当時のコラム・ブームを皮肉った『デヴィッド100コラム』という題の書き下し本さえある）。
|
||||
|
||||
『POPEYE』や『JJ』の登場には、旧来の「活字」によっては把握できなくなった、さまざまな新しい「意味」が込められていた。しかしその新しい「意味」はながいこと言葉によって把握されず、したがって社会のなかで正当に位置づけられることもなく、可能性はただの可能性のまま実を結ぶことなく萎れていった。橋本は『浮上せよと活字は言う』でそう論じたのだった。
|
||||
|
||||
『POPEYE』と『JJ』のうち、その後によく論じられ、関係者による証言も豊富に残されているのは『POPEYE』のほうである。代表的な著作としては、初期の編集部員として関わった椎根和による『POPEYE物語――若者を変えた伝説の雑誌』（新潮文庫）、この雑誌の愛読者だった赤田祐一による『証言構成『ポパイ』の時代―ある雑誌の奇妙な航海』（太田出版）がある。同誌を生み出した出版社、マガジンハウス（平凡出版）をめぐる本まで含めれば枚挙にいとまがない。なのでここでは、その後もあまり語られることのなかった『JJ』について、橋本の論と、その後について述べることにしたい。
|
||||
|
||||
「コーディネート」という実用的知性
|
||||
橋本は『JJ』のどこに新しさをみたのか。それは同誌に先立つ、先鋭的な女性ファッション誌の草分け『an・an』との対比により以下のように説明される。
|
||||
|
||||
「それが「新しい思想」であったのなら、まだ事態は活字人間にとって把握可能なものだっただろう。しかし『JJ』は思想誌ではなかった。「カタログ雑誌」とも呼ばれた、単なるファッション誌だった。「既にすべてはそこにあって、だから、そこには秩序立て（コーディネート）が必要だ」という、その思想だけが、コマ切れの写真の中から見えていただけだ。」（「三度断絶を論ず」）
|
||||
|
||||
ここで「思想誌」と呼ばれているのは『an・an』のことである。たしかに『an・an』は女性ファッション誌のあり方に一つの革命をもたらした。しかし、この先鋭的な雑誌が提示した「思想」は、日本の多くの女性たちにとって「現実の役に立たない」ものだった。その意味では外来の最新思想が、大半の日本の男にとっての身に沁みないのと同じである。
|
||||
|
||||
それに対して『JJ』は、過去の様々な時代の「思想＝ファッション」の流行がもたらしたデッドストック的な蓄積――男にとっての「積ん読本」のような使われないままの知性――に、一枚のスカーフの使い方に象徴されるような「コーディネート／秩序立て」という「実用」を提示した。そのことで『JJ』はファッションから「様式」というかたちで存在してきた伝統的な「規律」を放逐した、と橋本は言う。
|
||||
|
||||
規律なき伝統は「ニュートラ」と呼ばれ一般化すると同時に、日本の平凡な――「コンサバ」とも呼ばれたとおり、保守的でもある――女性たちに、「考えるということは、具体的に、この現実をどうするかを考えることだ」という知恵をももたらした。「そして、そのまんまどこかへ行ってしまったのだ」、と。
|
||||
|
||||
ところで、『浮上せよと活字は言う』で橋本治がこのように書いてから、すでに30年近い歳月が経った。『POPEYE』はその後、幾度もの方向転換ののち、「若者」というよりもずっと薹が立った「活字」好きな青年向けコラムマガジンとして存続している。他方、『JJ』はインターネットとSNSの時代が本格化するなかで急激に部数を落とし、2021年2月号をもって不定期刊行化とウェブ媒体への移行が発表された。紙媒体としては事実上の休刊である。
|
||||
|
||||
そのように『JJ』休刊が報じられた後、1990年代に同誌の熱心な読者だったという作家の鈴木涼美による『JJとその時代 女のコは雑誌に何を夢見たのか』（光文社新書）が刊行された。本書は実感的・体験的なすぐれた『JJ』論であるのみならず、『JJ』とその同時代の女性ファッション誌論、普遍的な雑誌論である。橋本が「そのまんまどこかへ行ってしまった」と嘆じて以後、「どこかへ行ってしまった」もの、つまり若い女性たちにとっての「現実」を語る言葉は長いこと不在だった。ようやく「活字」によってその現実が捉えられたのだとしたら、新たな知性もまたそこから「浮上」しうるのかもしれない。
|
||||
|
||||
本文中に登場した書籍一覧
|
||||
『POPEYE物語――若者を変えた伝説の雑誌』著 椎根和（新潮文庫 2010年）
|
||||
『証言構成『ポパイ』の時代―ある雑誌の奇妙な航海』著 赤田祐一（太田出版 2016年）
|
||||
『増補 浮上せよと活字は言う』著 橋本治（平凡社ライブラリー 2002年）
|
||||
『JJとその時代 女のコは雑誌に何を夢見たのか』著 鈴木涼美（光文社新書 2021年）
|
||||
|
||||
（当記事はModern Times 2022年2月に公開された記事の再掲載です）
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,883 @@
|
|||
# Claude 集成指南
|
||||
|
||||
**致 Claude Code：** 当用户要求您将此展示库中的组件集成到他们的项目中时，请仔细遵循这些说明。
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
此仓库是 Claude Code 基础设施组件的**参考库**。用户会要求您帮助将特定部分集成到他们的项目中。您的角色是：
|
||||
|
||||
1. **提出澄清性问题** 了解他们的项目结构
|
||||
2. **复制适当的文件**
|
||||
3. **为他们量身定制配置**
|
||||
4. **验证集成是否正常工作**
|
||||
|
||||
**核心原则：** 永远先询问，再假设项目结构。适用于一个项目的方案不一定适用于另一个项目。
|
||||
|
||||
---
|
||||
|
||||
## 技术栈兼容性检查
|
||||
|
||||
**关键：** 在集成技能之前，验证用户的技术栈是否与技能要求匹配。
|
||||
|
||||
### 前端技能
|
||||
|
||||
**frontend-dev-guidelines 要求：**
|
||||
- React (18+)
|
||||
- MUI v7
|
||||
- TanStack Query
|
||||
- TanStack Router
|
||||
- TypeScript
|
||||
|
||||
**集成前询问：**
|
||||
"您使用 React 和 MUI v7 吗？"
|
||||
|
||||
**如果答案是否定的：**
|
||||
```
|
||||
frontend-dev-guidelines 技能专门为 React + MUI v7 设计。我可以：
|
||||
1. 帮助您为 [他们的技术栈] 创建一个类似的技能，以这个为模板
|
||||
2. 提取与框架无关的模式（文件组织、性能等）
|
||||
3. 如果不相关则跳过此技能
|
||||
|
||||
您更倾向于哪种方式？
|
||||
```
|
||||
|
||||
### 后端技能
|
||||
|
||||
**backend-dev-guidelines 要求：**
|
||||
- Node.js/Express
|
||||
- TypeScript
|
||||
- Prisma ORM
|
||||
- Sentry
|
||||
|
||||
**集成前询问：**
|
||||
"您使用 Node.js 和 Express 以及 Prisma 吗？"
|
||||
|
||||
**如果答案是否定的：**
|
||||
```
|
||||
backend-dev-guidelines 技能专为 Express/Prisma 设计。我可以：
|
||||
1. 帮助您为 [他们的技术栈] 创建类似的指南，以这个为模板
|
||||
2. 提取架构模式（分层架构适用于任何框架）
|
||||
3. 跳过此技能
|
||||
|
||||
您更倾向于哪种方式？
|
||||
```
|
||||
|
||||
### 技术无关的技能
|
||||
|
||||
这些适用于**任何**技术栈：
|
||||
- ✅ **skill-developer** - 元技能，无需技术要求
|
||||
- ✅ **route-tester** - 仅需要 JWT cookie 认证（框架无关）
|
||||
- ✅ **error-tracking** - Sentry 适用于大多数技术栈
|
||||
|
||||
---
|
||||
|
||||
## 通用集成模式
|
||||
|
||||
当用户说：**"添加 [组件] 到我的项目"**
|
||||
|
||||
1. 识别组件类型（技能/钩子/智能体/命令）
|
||||
2. **检查技术栈兼容性**（适用于前端/后端技能）
|
||||
3. 询问他们的项目结构
|
||||
4. 复制文件或为他们适配技术栈
|
||||
5. 为他们量身定制配置
|
||||
6. 验证集成
|
||||
7. 提供后续步骤
|
||||
|
||||
---
|
||||
|
||||
## 集成技能
|
||||
|
||||
### 分步流程
|
||||
|
||||
**当用户请求技能**（例如，"添加 backend-dev-guidelines"）：
|
||||
|
||||
#### 1. 了解他们的项目
|
||||
|
||||
**询问这些问题：**
|
||||
- "您的项目结构是什么？单应用、monorepo 还是多服务？"
|
||||
- "您的 [后端/前端] 代码位于哪里？"
|
||||
- "您使用什么框架/技术？"
|
||||
|
||||
#### 2. 复制技能
|
||||
|
||||
```bash
|
||||
cp -r /path/to/showcase/.claude/skills/[skill-name] \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/skills/
|
||||
```
|
||||
|
||||
#### 3. 处理 skill-rules.json
|
||||
|
||||
**检查是否存在：**
|
||||
```bash
|
||||
ls $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json
|
||||
```
|
||||
|
||||
**如果不存在：**
|
||||
- 从展示库复制模板
|
||||
- 删除用户不需要的技能
|
||||
- 为他们的项目定制
|
||||
|
||||
**如果存在：**
|
||||
- 读取他们当前的 skill-rules.json
|
||||
- 添加新的技能条目
|
||||
- 小心合并，避免破坏现有技能
|
||||
|
||||
#### 4. 自定义路径模式
|
||||
|
||||
**关键：** 更新 `skill-rules.json` 中的 `pathPatterns` 以匹配他们的结构：
|
||||
|
||||
**示例 - 用户有 monorepo：**
|
||||
```json
|
||||
{
|
||||
"backend-dev-guidelines": {
|
||||
"fileTriggers": {
|
||||
"pathPatterns": [
|
||||
"packages/api/src/**/*.ts",
|
||||
"packages/server/src/**/*.ts",
|
||||
"apps/backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**示例 - 用户有单个后端：**
|
||||
```json
|
||||
{
|
||||
"backend-dev-guidelines": {
|
||||
"fileTriggers": {
|
||||
"pathPatterns": [
|
||||
"src/**/*.ts",
|
||||
"backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**安全通用模式**（不确定时使用）：
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"**/*.ts", // 所有 TypeScript 文件
|
||||
"src/**/*.ts", // 常见 src 目录
|
||||
"backend/**/*.ts" // 常见 backend 目录
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. 验证集成
|
||||
|
||||
```bash
|
||||
# 检查技能是否已复制
|
||||
ls -la $CLAUDE_PROJECT_DIR/.claude/skills/[skill-name]
|
||||
|
||||
# 验证 skill-rules.json 语法
|
||||
cat $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json | jq .
|
||||
```
|
||||
|
||||
**告诉用户：** "尝试编辑 [他们的后端路径] 中的文件，技能应该会激活。"
|
||||
|
||||
---
|
||||
|
||||
### 技能特定说明
|
||||
|
||||
#### backend-dev-guidelines
|
||||
- **技术要求：** Node.js/Express、Prisma、TypeScript、Sentry
|
||||
- **询问：** "您使用 Express 和 Prisma 吗？" "您的后端代码在哪里？"
|
||||
- **如果技术栈不同：** 提供以这个为模板进行适配
|
||||
- **自定义：** pathPatterns
|
||||
- **示例路径：** `api/`、`server/`、`backend/`、`services/*/src/`
|
||||
- **适配提示：** 架构模式（路由→控制器→服务）适用于大多数框架
|
||||
|
||||
#### frontend-dev-guidelines
|
||||
- **技术要求：** React 18+、MUI v7、TanStack Query/Router、TypeScript
|
||||
- **询问：** "您使用 React 和 MUI v7 吗？" "您的前端代码在哪里？"
|
||||
- **如果技术栈不同：** 提供创建适配版本（Vue、Angular 等）
|
||||
- **自定义：** pathPatterns + 所有框架特定示例
|
||||
- **示例路径：** `frontend/`、`client/`、`web/`、`apps/web/src/`
|
||||
- **适配提示：** 文件组织和性能模式可以迁移，组件代码不行
|
||||
|
||||
#### route-tester
|
||||
- **技术要求：** 基于 JWT cookie 的认证（框架无关）
|
||||
- **询问：** "您使用基于 JWT cookie 的认证吗？"
|
||||
- **如果答案是否定：** "此技能专为 JWT cookie 设计。要我为 [他们的认证类型] 适配它或跳过吗？"
|
||||
- **自定义：** 服务 URL、认证模式
|
||||
- **适用于：** 使用 JWT cookie 的任何后端框架
|
||||
|
||||
#### error-tracking
|
||||
- **技术要求：** Sentry（适用于大多数后端）
|
||||
- **询问：** "您使用 Sentry 吗？" "您的后端代码在哪里？"
|
||||
- **如果没有 Sentry：** "要以此作为 [他们的错误跟踪] 的模板吗？"
|
||||
- **自定义：** pathPatterns
|
||||
- **适配提示：** 错误跟踪理念适用于其他工具（Rollbar、Bugsnag 等）
|
||||
|
||||
#### skill-developer
|
||||
- **技术要求：** 无！
|
||||
- **原样复制** - 元技能，完全通用，教授为**任何**技术栈创建技能
|
||||
|
||||
---
|
||||
|
||||
## 为不同技术栈适配技能
|
||||
|
||||
当用户的技术栈与技能要求不同时，您有选择：
|
||||
|
||||
### 选项 1：适配现有技能（推荐）
|
||||
|
||||
**何时使用：** 用户想要针对不同技术有类似的指南
|
||||
|
||||
**流程：**
|
||||
1. **复制技能作为起点：**
|
||||
```bash
|
||||
cp -r showcase/.claude/skills/frontend-dev-guidelines \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/skills/vue-dev-guidelines
|
||||
```
|
||||
|
||||
2. **识别需要更改的部分：**
|
||||
- 框架特定代码示例（React → Vue）
|
||||
- 库 API（MUI → Vuetify/PrimeVue）
|
||||
- 导入语句
|
||||
- 组件模式
|
||||
|
||||
3. **保留可以迁移的部分：**
|
||||
- 文件组织原则
|
||||
- 性能优化策略
|
||||
- TypeScript 标准
|
||||
- 通用最佳实践
|
||||
|
||||
4. **系统地替换示例：**
|
||||
- 询问用户他们技术栈中的等效模式
|
||||
- 将代码示例更新为他们的框架
|
||||
- 保持整体结构和章节
|
||||
|
||||
5. **更新技能名称和触发器：**
|
||||
- 适当地重命名技能
|
||||
- 更新 skill-rules.json 触发器以适应他们的技术栈
|
||||
- 测试激活
|
||||
|
||||
**示例 - 为 Vue 适配 frontend-dev-guidelines：**
|
||||
```
|
||||
我将基于 React 技能结构创建 vue-dev-guidelines：
|
||||
- 将 React.FC → Vue defineComponent
|
||||
- 将 useSuspenseQuery → Vue composables
|
||||
- 将 MUI 组件 → [他们的组件库]
|
||||
- 保留：文件组织、性能模式、TypeScript 指南
|
||||
|
||||
这需要几分钟时间。听起来不错吧？
|
||||
```
|
||||
|
||||
### 选项 2：提取与框架无关的模式
|
||||
|
||||
**何时使用：** 技术栈差异很大，但核心原则适用
|
||||
|
||||
**流程：**
|
||||
1. 阅读现有技能
|
||||
2. 识别与框架无关的模式：
|
||||
- 分层架构（后端）
|
||||
- 文件组织策略
|
||||
- 性能优化原则
|
||||
- 测试策略
|
||||
- 错误处理理念
|
||||
|
||||
3. 创建仅包含这些模式的新技能
|
||||
4. 用户可以稍后添加框架特定示例
|
||||
|
||||
**示例：**
|
||||
```
|
||||
backend-dev-guidelines 使用 Express，但分层架构
|
||||
（路由 → 控制器 → 服务 → 仓库）也适用于 Django。
|
||||
|
||||
我可以创建一个包含以下内容的技能：
|
||||
- 分层架构模式
|
||||
- 关注点分离原则
|
||||
- 错误处理最佳实践
|
||||
- 测试策略
|
||||
|
||||
然后您可以在建立模式时添加 Django 特定示例。
|
||||
```
|
||||
|
||||
### 选项 3：仅用作参考
|
||||
|
||||
**何时使用：** 差异太大无法适配，但用户想要灵感
|
||||
|
||||
**流程：**
|
||||
1. 用户浏览现有技能
|
||||
2. 您帮助从头创建新技能
|
||||
3. 使用现有技能的结构作为模板
|
||||
4. 遵循模块化模式（主文件 + 资源文件）
|
||||
|
||||
### 通常跨技术栈迁移的内容
|
||||
|
||||
**架构与组织：**
|
||||
- ✅ 分层架构（路由/控制器/服务模式）
|
||||
- ✅ 关注点分离
|
||||
- ✅ 文件组织策略（features/ 模式）
|
||||
- ✅ 渐进式披露（主文件 + 资源文件）
|
||||
- ✅ 仓库模式用于数据访问
|
||||
|
||||
**开发实践：**
|
||||
- ✅ 错误处理理念
|
||||
- ✅ 输入验证重要性
|
||||
- ✅ 测试策略
|
||||
- ✅ 性能优化原则
|
||||
- ✅ TypeScript 最佳实践
|
||||
|
||||
**框架特定代码：**
|
||||
- ❌ React hooks → 不要迁移到 Vue/Angular
|
||||
- ❌ MUI 组件 → 不同的组件库
|
||||
- ❌ Prisma 查询 → 不同的 ORM 语法
|
||||
- ❌ Express middleware → 不同的框架模式
|
||||
- ❌ 路由实现 → 框架特定
|
||||
|
||||
### 何时推荐适配 vs 跳过
|
||||
|
||||
**推荐适配如果：**
|
||||
- 用户想要针对他们技术栈的类似指南
|
||||
- 核心模式适用（分层架构等）
|
||||
- 用户有时间帮助处理框架特定示例
|
||||
|
||||
**推荐跳过如果：**
|
||||
- 技术栈完全不同
|
||||
- 用户不需要这些模式
|
||||
- 适配需要太长时间
|
||||
- 用户更喜欢从头创建
|
||||
|
||||
---
|
||||
|
||||
## 集成钩子
|
||||
|
||||
### 必需钩子（始终可以安全复制）
|
||||
|
||||
#### skill-activation-prompt (UserPromptSubmit)
|
||||
|
||||
**用途：** 根据用户提示自动建议技能
|
||||
|
||||
**集成（无需自定义）：**
|
||||
|
||||
```bash
|
||||
# 复制两个文件
|
||||
cp showcase/.claude/hooks/skill-activation-prompt.sh \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
cp showcase/.claude/hooks/skill-activation-prompt.ts \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
|
||||
# 设为可执行
|
||||
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh
|
||||
|
||||
# 安装依赖（如需要）
|
||||
if [ -f "showcase/.claude/hooks/package.json" ]; then
|
||||
cp showcase/.claude/hooks/package.json \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
cd $CLAUDE_PROJECT_DIR/.claude/hooks && npm install
|
||||
fi
|
||||
```
|
||||
|
||||
**添加到 settings.json：**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**此钩子完全通用** - 任何地方都适用，无需自定义！
|
||||
|
||||
#### post-tool-use-tracker (PostToolUse)
|
||||
|
||||
**用途：** 跟踪文件更改用于上下文管理
|
||||
|
||||
**集成（无需自定义）：**
|
||||
|
||||
```bash
|
||||
# 复制文件
|
||||
cp showcase/.claude/hooks/post-tool-use-tracker.sh \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/hooks/
|
||||
|
||||
# 设为可执行
|
||||
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh
|
||||
```
|
||||
|
||||
**添加到 settings.json：**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**此钩子完全通用** - 自动检测项目结构！
|
||||
|
||||
---
|
||||
|
||||
### 可选钩子（需要大量自定义）
|
||||
|
||||
#### tsc-check.sh 和 trigger-build-resolver.sh (Stop hooks)
|
||||
|
||||
⚠️ **警告：** 这些钩子配置用于特定的多服务 monorepo 结构。
|
||||
|
||||
**集成前询问：**
|
||||
1. "您有包含多个 TypeScript 服务的 monorepo 吗？"
|
||||
2. "您的服务目录名称是什么？"
|
||||
3. "您的 tsconfig.json 文件位于哪里？"
|
||||
|
||||
**对于简单项目（单个服务）：**
|
||||
- **建议跳过** 这些钩子
|
||||
- 它们对于单服务项目来说过于复杂
|
||||
- 用户可以手动运行 `tsc --noEmit`
|
||||
|
||||
**对于复杂项目（多服务 monorepo）：**
|
||||
|
||||
1. 复制文件
|
||||
2. **必须编辑** tsc-check.sh - 找到此部分：
|
||||
```bash
|
||||
case "$repo" in
|
||||
email|exports|form|frontend|projects|uploads|users|utilities|events|database)
|
||||
echo "$repo"
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
3. 用用户的实际服务名称替换：
|
||||
```bash
|
||||
case "$repo" in
|
||||
api|web|auth|payments|notifications) # ← 用户的服务
|
||||
echo "$repo"
|
||||
return 0
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
4. 添加到 settings.json 前手动测试：
|
||||
```bash
|
||||
./.claude/hooks/tsc-check.sh
|
||||
```
|
||||
|
||||
**重要：** 如果此钩子失败，它将阻止 Stop 事件。只有在确信它适用于他们的设置时才添加。
|
||||
|
||||
---
|
||||
|
||||
## 集成智能体
|
||||
|
||||
**智能体是独立的** - 最容易集成！
|
||||
|
||||
### 标准智能体集成
|
||||
|
||||
```bash
|
||||
# 复制智能体文件
|
||||
cp showcase/.claude/agents/[agent-name].md \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/agents/
|
||||
```
|
||||
|
||||
**就是这样！** 智能体立即工作，无需配置。
|
||||
|
||||
### 检查硬编码路径
|
||||
|
||||
一些智能体可能引用路径。**复制前，阅读智能体文件并检查：**
|
||||
|
||||
- `~/git/old-project/` → 应该是 `$CLAUDE_PROJECT_DIR` 或 `.`
|
||||
- `/root/git/project/` → 应该是 `$CLAUDE_PROJECT_DIR` 或 `.`
|
||||
- 硬编码的截图路径 → 询问用户他们希望在哪里保存截图
|
||||
|
||||
**如果找到，更新它们：**
|
||||
```bash
|
||||
sed -i 's|~/git/old-project/|.|g' $CLAUDE_PROJECT_DIR/.claude/agents/[agent].md
|
||||
sed -i 's|/root/git/.*PROJECT.*DIR|$CLAUDE_PROJECT_DIR|g' \
|
||||
$CLAUDE_PROJECT_DIR/.claude/agents/[agent].md
|
||||
```
|
||||
|
||||
### 智能体特定说明
|
||||
|
||||
**auth-route-tester / auth-route-debugger:**
|
||||
- 需要用户项目中的基于 JWT cookie 的认证
|
||||
- 询问："您使用 JWT cookie 进行认证吗？"
|
||||
- 如果答案是否定："这些智能体用于 JWT cookie 认证。跳过它们或要我适配？"
|
||||
|
||||
**frontend-error-fixer:**
|
||||
- 可能引用截图路径
|
||||
- 询问："截图应该保存在哪里？"
|
||||
|
||||
**所有其他智能体：**
|
||||
- 原样复制，它们完全通用
|
||||
|
||||
---
|
||||
|
||||
## 集成斜杠命令
|
||||
|
||||
```bash
|
||||
# 复制命令文件
|
||||
cp showcase/.claude/commands/[command].md \\
|
||||
$CLAUDE_PROJECT_DIR/.claude/commands/
|
||||
```
|
||||
|
||||
### 自定义路径
|
||||
|
||||
命令可能引用 dev docs 路径。**检查并更新：**
|
||||
|
||||
**dev-docs 和 dev-docs-update:**
|
||||
- 查找 `dev/active/` 路径引用
|
||||
- 询问："您希望在哪里存储开发文档？"
|
||||
- 更新命令文件中的路径
|
||||
|
||||
**route-research-for-testing:**
|
||||
- 可能引用服务路径
|
||||
- 询问他们关于 API 结构
|
||||
|
||||
---
|
||||
|
||||
## 通用模式与最佳实践
|
||||
|
||||
### 模式：询问项目结构
|
||||
|
||||
**不要假设：**
|
||||
- ❌ "我将为您的 blog-api 服务添加这个"
|
||||
- ❌ "为您的 frontend 目录配置"
|
||||
|
||||
**要询问：**
|
||||
- ✅ "您的项目结构是什么？Monorepo 还是单应用？"
|
||||
- ✅ "您的后端代码位于哪里？"
|
||||
- ✅ "您使用 workspaces 还是有多服务？"
|
||||
|
||||
### 模式：自定义 skill-rules.json
|
||||
|
||||
**用户有带 workspaces 的 monorepo：**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"packages/*/src/**/*.ts",
|
||||
"apps/*/src/**/*.tsx"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**用户有 Nx monorepo：**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"apps/api/src/**/*.ts",
|
||||
"libs/*/src/**/*.ts"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**用户有简单结构：**
|
||||
```json
|
||||
{
|
||||
"pathPatterns": [
|
||||
"src/**/*.ts",
|
||||
"backend/**/*.ts"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 模式：settings.json 集成
|
||||
|
||||
**永远不要直接复制展示库的 settings.json！**
|
||||
|
||||
相反，**提取并合并** 他们需要的部分：
|
||||
|
||||
1. 读取他们现有的 settings.json
|
||||
2. 添加他们想要的钩子配置
|
||||
3. 保留他们现有的配置
|
||||
|
||||
**示例合并：**
|
||||
```json
|
||||
{
|
||||
// ... 他们现有的配置 ...
|
||||
"hooks": {
|
||||
// ... 他们现有的钩子 ...
|
||||
"UserPromptSubmit": [ // ← 添加此部分
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 验证清单
|
||||
|
||||
集成后，**验证这些项目：**
|
||||
|
||||
```bash
|
||||
# 1. 钩子可执行
|
||||
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh
|
||||
# 应该显示：-rwxr-xr-x
|
||||
|
||||
# 2. skill-rules.json 是有效 JSON
|
||||
cat $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json | jq .
|
||||
# 应该无错误解析
|
||||
|
||||
# 3. 钩子依赖已安装（如有 TypeScript 钩子）
|
||||
ls $CLAUDE_PROJECT_DIR/.claude/hooks/node_modules/
|
||||
# 如果存在 package.json 应该显示包
|
||||
|
||||
# 4. settings.json 是有效 JSON
|
||||
cat $CLAUDE_PROJECT_DIR/.claude/settings.json | jq .
|
||||
# 应该无错误解析
|
||||
```
|
||||
|
||||
**然后请用户测试：**
|
||||
- "尝试编辑 [相关路径] 中的文件 - 技能应该激活"
|
||||
- "尝试问我关于 [主题] 的问题 - 我应该建议技能"
|
||||
|
||||
---
|
||||
|
||||
## 要避免的常见错误
|
||||
|
||||
### ❌ 不要：原样复制 settings.json
|
||||
**为什么：** Stop 钩子引用不存在的服务
|
||||
**应该做：** 仅提取 UserPromptSubmit 和 PostToolUse 部分
|
||||
|
||||
### ❌ 不要：保留示例服务名称
|
||||
**为什么：** 用户没有 blog-api、auth-service 等
|
||||
**应该做：** 询问他们的实际结构并更新
|
||||
|
||||
### ❌ 不要：跳过使钩子可执行
|
||||
**为什么：** 没有执行权限钩子不会运行
|
||||
**应该做：** 复制后始终运行 `chmod +x`
|
||||
|
||||
### ❌ 不要：假设 monorepo 结构
|
||||
**为什么：** 大多数项目是单服务
|
||||
**应该做：** 首先询问，然后自定义
|
||||
|
||||
### ❌ 不要：一次添加所有技能
|
||||
**为什么：** 令人不知所措，可能不都相关
|
||||
**应该做：** 询问哪些技能与他们的工作相关
|
||||
|
||||
### ❌ 不要：在未测试的情况下复制 Stop 钩子
|
||||
**为什么：** 如果失败它们可能阻止 Stop 事件
|
||||
**应该做：** 首先手动测试，只有在工作时才添加
|
||||
|
||||
---
|
||||
|
||||
## 示例集成对话
|
||||
|
||||
### 示例 1：添加后端技能
|
||||
|
||||
**用户：** "将 backend-dev-guidelines 技能添加到我的项目"
|
||||
|
||||
**Claude 应该回应：**
|
||||
```
|
||||
我将添加 backend-dev-guidelines 技能。首先，我需要了解
|
||||
您的项目结构：
|
||||
|
||||
1. 这是有多个服务的 monorepo 还是单个后端应用？
|
||||
2. 您的后端代码位于哪里？（例如 src/、backend/、server/）
|
||||
3. 您使用 Express.js 吗？
|
||||
```
|
||||
|
||||
**用户：** "单应用，代码在 src/api/ 中，是的我们使用 Express"
|
||||
|
||||
**Claude 应该：**
|
||||
1. 复制技能目录
|
||||
2. 使用 pathPattern 更新 skill-rules.json：`"src/api/**/*.ts"`
|
||||
3. 验证复制正确
|
||||
4. 回应：
|
||||
```
|
||||
✅ 已添加 backend-dev-guidelines 技能！
|
||||
|
||||
配置：
|
||||
- 当编辑 src/api/ 中的文件时技能触发
|
||||
- 由 "controller"、"service"、"route"、"API" 等关键词激活
|
||||
|
||||
试试看：编辑 src/api/ 中的文件，您应该看到技能建议。
|
||||
```
|
||||
|
||||
### 示例 2：设置钩子
|
||||
|
||||
**用户：** "设置技能激活钩子"
|
||||
|
||||
**Claude 应该回应：**
|
||||
```
|
||||
我将设置技能自动激活系统。这需要两个钩子：
|
||||
1. skill-activation-prompt - 根据您的提示建议技能
|
||||
2. post-tool-use-tracker - 跟踪文件更改
|
||||
|
||||
您已经有一个 .claude/settings.json 文件，还是我应该创建一个？
|
||||
```
|
||||
|
||||
**用户：** "我已经有 settings.json"
|
||||
|
||||
**Claude 应该：**
|
||||
1. 读取他们的 settings.json
|
||||
2. 复制两个钩子文件
|
||||
3. 在 hooks 目录运行 npm install
|
||||
4. 将钩子配置添加到他们的 settings.json（保留现有配置）
|
||||
5. 使钩子可执行
|
||||
6. 回应：
|
||||
```
|
||||
✅ 技能激活钩子已安装！
|
||||
|
||||
我所做的：
|
||||
- 复制了 skill-activation-prompt 钩子
|
||||
- 复制了 post-tool-use-tracker 钩子
|
||||
- 安装了依赖
|
||||
- 添加到您的 settings.json
|
||||
|
||||
测试一下：问我"帮助进行后端开发"，我应该建议
|
||||
backend-dev-guidelines 技能。
|
||||
```
|
||||
|
||||
### 示例 3：添加智能体
|
||||
|
||||
**用户：** "添加 code-architecture-reviewer 智能体"
|
||||
|
||||
**Claude 应该：**
|
||||
```
|
||||
code-architecture-reviewer 智能体审查代码的架构问题
|
||||
和最佳实践。此智能体独立工作，无需配置。
|
||||
|
||||
我现在将其复制到您的 .claude/agents/ 目录。
|
||||
```
|
||||
|
||||
**然后：**
|
||||
1. 复制智能体文件
|
||||
2. 回应：
|
||||
```
|
||||
✅ 已添加 code-architecture-reviewer 智能体！
|
||||
|
||||
通过运行 Task 工具使用它：
|
||||
- subagent_type: "code-architecture-reviewer"
|
||||
- prompt: 要审查的代码描述
|
||||
|
||||
智能体将审查您的代码并提供架构反馈。
|
||||
```
|
||||
|
||||
### 示例 3：技术栈不匹配
|
||||
|
||||
**用户：** "将 frontend-dev-guidelines 技能添加到我的 Vue 项目"
|
||||
|
||||
**Claude 应该：**
|
||||
```
|
||||
我看到您使用 Vue。frontend-dev-guidelines 技能专门为
|
||||
React + MUI v7 设计。我有几个选项：
|
||||
|
||||
选项 1（推荐）：我可以创建 vue-dev-guidelines 技能，使用
|
||||
React 技能作为模板。我将适配：
|
||||
- Vue 的组件模式（Composition API、defineComponent）
|
||||
- 将 MUI 示例替换为您的组件库
|
||||
- 适配 Vue 模式的数据获取
|
||||
- 保留：文件组织、性能原则、TypeScript 标准
|
||||
|
||||
选项 2：仅提取与框架无关的模式（文件组织、
|
||||
性能、测试）不包含 React 特定代码。
|
||||
|
||||
选项 3：跳过它，帮助您从头创建 Vue 指南。
|
||||
|
||||
您更倾向于哪个选项？
|
||||
```
|
||||
|
||||
**用户：** "选项 1 听起来不错，我使用 Vuetify"
|
||||
|
||||
**Claude 应该：**
|
||||
1. 将 frontend-dev-guidelines 复制为 vue-dev-guidelines
|
||||
2. 逐个资源文件
|
||||
3. 将 React 模式替换为 Vue Composition API
|
||||
4. 将 MUI 组件替换为 Vuetify
|
||||
5. 更新 skill-rules.json 包含 Vue 特定触发器（.vue 文件）
|
||||
6. 回应：
|
||||
```
|
||||
✅ 已创建适用于 Vue 3 + Vuetify 的 vue-dev-guidelines 技能！
|
||||
|
||||
我更改的内容：
|
||||
- React.FC 组件 → Vue defineComponent
|
||||
- MUI v7 示例 → Vuetify 组件
|
||||
- TanStack Query → 您的数据获取方法
|
||||
- 文件模式 → .vue 文件
|
||||
|
||||
我保留的内容：
|
||||
- 文件组织（features/ 模式）
|
||||
- 性能优化策略
|
||||
- TypeScript 标准
|
||||
- 加载/错误状态原则
|
||||
|
||||
试试编辑 .vue 文件 - 技能应该激活。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速参考表
|
||||
|
||||
### 需要自定义什么？
|
||||
|
||||
| 组件 | 技术要求 | 自定义 | 询问什么 |
|
||||
|-----------|------------------|--------------|-------------|
|
||||
| **skill-developer** | 无 | ✅ 无 | 原样复制 |
|
||||
| **backend-dev-guidelines** | Express/Prisma/Node | ⚠️ 路径 + 技术检查 | "使用 Express/Prisma？" "后端在哪里？" |
|
||||
| **frontend-dev-guidelines** | React/MUI v7 | ⚠️⚠️ 路径 + 框架 | "使用 React/MUI v7？" "前端在哪里？" |
|
||||
| **route-tester** | JWT cookies | ⚠️ 认证 + 路径 | "JWT cookie 认证？" |
|
||||
| **error-tracking** | Sentry | ⚠️ 路径 | "使用 Sentry？" "后端在哪里？" |
|
||||
| **skill-activation-prompt** | ✅ 无 | 原样复制 |
|
||||
| **post-tool-use-tracker** | ✅ 无 | 原样复制 |
|
||||
| **tsc-check** | ⚠️⚠️⚠️ 大量 | "Monorepo 还是单服务？" |
|
||||
| **所有智能体** | ✅ 最小 | 检查路径 |
|
||||
| **所有命令** | ⚠️ 路径 | "dev docs 放在哪里？" |
|
||||
|
||||
### 何时建议跳过
|
||||
|
||||
| 组件 | 跳过如果... |
|
||||
|-----------|-----------|
|
||||
| **tsc-check 钩子** | 单服务项目或不同构建设置 |
|
||||
| **route-tester** | 不使用基于 JWT cookie 的认证 |
|
||||
| **frontend-dev-guidelines** | 不使用 React + MUI |
|
||||
| **认证智能体** | 不使用基于 JWT cookie 的认证 |
|
||||
|
||||
---
|
||||
|
||||
## Claude 的最后提示
|
||||
|
||||
**当用户说"全部添加"时：**
|
||||
- 从必需品开始：技能激活钩子 + 1-2 个相关技能
|
||||
- 不要用所有 5 个技能 + 10 个智能体让他们感到不知所措
|
||||
- 询问他们实际需要什么
|
||||
|
||||
**当某事不起作用时：**
|
||||
- 检查验证清单
|
||||
- 验证路径匹配他们的结构
|
||||
- 手动测试钩子
|
||||
- 检查 JSON 语法错误
|
||||
|
||||
**当用户不确定时：**
|
||||
- 建议仅从技能激活钩子开始
|
||||
- 添加后端**或**前端技能（他们使用的）
|
||||
- 根据需要稍后添加更多
|
||||
|
||||
**始终解释您在做什么：**
|
||||
- 显示您运行的命令
|
||||
- 解释为什么询问问题
|
||||
- 集成后提供清晰的后续步骤
|
||||
|
||||
---
|
||||
|
||||
**记住：** 这是一个参考库，不是可运行的应用程序。您的任务是帮助用户为他们的特定项目结构精选和适配组件。
|
||||
|
|
@ -0,0 +1,359 @@
|
|||
# Claude Code 基础设施展示库
|
||||
|
||||
**精心策划的生产就绪 Claude Code 基础设施参考库。**
|
||||
|
||||
源于管理复杂 TypeScript 微服务项目的 6 个月实际使用经验，本展示库提供了解决"技能无法自动激活"问题的模式和系统，并将 Claude Code 扩展到企业级开发。
|
||||
|
||||
> **这不是一个可运行的应用程序** - 它是一个参考库。将您需要的内容复制到您自己的项目中即可。
|
||||
|
||||
---
|
||||
|
||||
## 内容概览
|
||||
|
||||
**生产就绪的基础设施包含：**
|
||||
- ✅ 通过钩子实现技能自动激活
|
||||
- ✅ 模块化技能模式（500 行规则与渐进式披露）
|
||||
- ✅ 专门处理复杂任务的智能体
|
||||
- ✅ 能在上下文重置后存活的开发文档系统
|
||||
- ✅ 使用通用博客域的综合示例
|
||||
|
||||
**构建所需时间投入：** 6 个月的迭代开发
|
||||
**集成到您项目的时间：** 15-30 分钟
|
||||
|
||||
---
|
||||
|
||||
## 快速开始 - 选择您的路径
|
||||
|
||||
### 🤖 使用 Claude Code 进行集成？
|
||||
|
||||
**Claude：** 阅读 [`CLAUDE_INTEGRATION_GUIDE.md`](CLAUDE_INTEGRATION_GUIDE.md) 获取针对 AI 辅助设置的详细集成说明。
|
||||
|
||||
### 🎯 我想要技能自动激活
|
||||
|
||||
**突破性功能：** 真正能在您需要时激活的技能。
|
||||
|
||||
**您需要的：**
|
||||
1. 技能激活钩子（2 个文件）
|
||||
2. 与您工作相关的 1-2 个技能
|
||||
3. 15 分钟时间
|
||||
|
||||
**👉 [设置指南：.claude/hooks/README.md](.claude/hooks/README.md)**
|
||||
|
||||
### 📚 我想要添加一个技能
|
||||
|
||||
浏览[技能目录](.claude/skills/)并复制您需要的内容。
|
||||
|
||||
**可用技能：**
|
||||
- **backend-dev-guidelines** - Node.js/Express/TypeScript 模式
|
||||
- **frontend-dev-guidelines** - React/TypeScript/MUI v7 模式
|
||||
- **skill-developer** - 用于创建技能的元技能
|
||||
- **route-tester** - 测试已认证的 API 路由
|
||||
- **error-tracking** - Sentry 集成模式
|
||||
|
||||
**👉 [技能指南：.claude/skills/README.md](.claude/skills/README.md)**
|
||||
|
||||
### 🤖 我想要专门的智能体
|
||||
|
||||
10 个生产就绪的智能体，适用于复杂任务：
|
||||
- 代码架构审查
|
||||
- 重构辅助
|
||||
- 文档生成
|
||||
- 错误调试
|
||||
- 等等...
|
||||
|
||||
**👉 [智能体指南：.claude/agents/README.md](.claude/agents/README.md)**
|
||||
|
||||
---
|
||||
|
||||
## 这与别的方案有何不同？
|
||||
|
||||
### 自动激活突破
|
||||
|
||||
**问题：** Claude Code 技能只是静静地待在那里。您必须记住使用它们。
|
||||
|
||||
**解决方案：** UserPromptSubmit 钩子能够：
|
||||
- 分析您的提示
|
||||
- 检查文件上下文
|
||||
- 自动建议相关技能
|
||||
- 通过 `skill-rules.json` 配置工作
|
||||
|
||||
**结果：** 技能在您需要时激活，而不是在您记住时激活。
|
||||
|
||||
### 生产验证模式
|
||||
|
||||
这些不是理论示例 - 它们是从以下项目中提取的：
|
||||
- ✅ 生产环境中的 6 个微服务
|
||||
- ✅ 50,000+ 行 TypeScript 代码
|
||||
- ✅ 具有复杂数据网格的 React 前端
|
||||
- ✅ 复杂的工作流引擎
|
||||
- ✅ 6 个月的日常 Claude Code 使用经验
|
||||
|
||||
这些模式有效是因为它们解决了实际问题。
|
||||
|
||||
### 模块化技能（500 行规则）
|
||||
|
||||
大型技能会触及上下文限制。解决方案是：
|
||||
|
||||
```
|
||||
技能名称/
|
||||
SKILL.md # <500 行，高级指南
|
||||
resources/
|
||||
topic-1.md # 每个 <500 行
|
||||
topic-2.md
|
||||
topic-3.md
|
||||
```
|
||||
|
||||
**渐进式披露：** Claude 首先加载主技能，仅在需要时加载资源文件。
|
||||
|
||||
---
|
||||
|
||||
## 仓库结构
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── skills/ # 5 个生产技能
|
||||
│ ├── backend-dev-guidelines/ (12 个资源文件)
|
||||
│ ├── frontend-dev-guidelines/ (11 个资源文件)
|
||||
│ ├── skill-developer/ (7 个资源文件)
|
||||
│ ├── route-tester/
|
||||
│ ├── error-tracking/
|
||||
│ └── skill-rules.json # 技能激活配置
|
||||
├── hooks/ # 6 个自动化钩子
|
||||
│ ├── skill-activation-prompt.* (必需)
|
||||
│ ├── post-tool-use-tracker.sh (必需)
|
||||
│ ├── tsc-check.sh (可选，需要自定义)
|
||||
│ └── trigger-build-resolver.sh (可选)
|
||||
├── agents/ # 10 个专门智能体
|
||||
│ ├── code-architecture-reviewer.md
|
||||
│ ├── refactor-planner.md
|
||||
│ ├── frontend-error-fixer.md
|
||||
│ └── ... 7 个更多
|
||||
└── commands/ # 3 个斜杠命令
|
||||
├── dev-docs.md
|
||||
└── ...
|
||||
|
||||
dev/
|
||||
└── active/ # Dev Docs 模式示例
|
||||
└── public-infrastructure-repo/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 组件目录
|
||||
|
||||
### 🎨 技能 (5)
|
||||
|
||||
| 技能 | 行数 | 用途 | 适用于 |
|
||||
|------|------|------|--------|
|
||||
| [**skill-developer**](.claude/skills/skill-developer/) | 426 | 创建和管理技能 | 元开发 |
|
||||
| [**backend-dev-guidelines**](.claude/skills/backend-dev-guidelines/) | 304 | Express/Prisma/Sentry 模式 | 后端 API |
|
||||
| [**frontend-dev-guidelines**](.claude/skills/frontend-dev-guidelines/) | 398 | React/MUI v7/TypeScript | React 前端 |
|
||||
| [**route-tester**](.claude/skills/route-tester/) | 389 | 测试已认证路由 | API 测试 |
|
||||
| [**error-tracking**](.claude/skills/error-tracking/) | ~250 | Sentry 集成 | 错误监控 |
|
||||
|
||||
**所有技能都遵循模块化模式** - 主文件 + 渐进式披露的资源文件。
|
||||
|
||||
**👉 [如何集成技能 →](.claude/skills/README.md)**
|
||||
|
||||
### 🪝 钩子 (6)
|
||||
|
||||
| 钩子 | 类型 | 必需？ | 自定义需求 |
|
||||
|------|------|--------|------------|
|
||||
| skill-activation-prompt | UserPromptSubmit | ✅ 是 | ✅ 无需 |
|
||||
| post-tool-use-tracker | PostToolUse | ✅ 是 | ✅ 无需 |
|
||||
| tsc-check | Stop | ⚠️ 可选 | ⚠️ 大量 - 仅限 monorepo |
|
||||
| trigger-build-resolver | Stop | ⚠️ 可选 | ⚠️ 大量 - 仅限 monorepo |
|
||||
| error-handling-reminder | Stop | ⚠️ 可选 | ⚠️ 中等 |
|
||||
| stop-build-check-enhanced | Stop | ⚠️ 可选 | ⚠️ 中等 |
|
||||
|
||||
**从两个必需钩子开始** - 它们实现技能自动激活，开箱即用。
|
||||
|
||||
**👉 [钩子设置指南 →](.claude/hooks/README.md)**
|
||||
|
||||
### 🤖 智能体 (10)
|
||||
|
||||
**独立运行 - 只需复制即可使用！**
|
||||
|
||||
| 智能体 | 用途 |
|
||||
|-------|------|
|
||||
| code-architecture-reviewer | 审查代码架构一致性 |
|
||||
| code-refactor-master | 规划和执行重构 |
|
||||
| documentation-architect | 生成综合文档 |
|
||||
| frontend-error-fixer | 调试前端错误 |
|
||||
| plan-reviewer | 审查开发计划 |
|
||||
| refactor-planner | 创建重构策略 |
|
||||
| web-research-specialist | 在线研究技术问题 |
|
||||
| auth-route-tester | 测试已认证端点 |
|
||||
| auth-route-debugger | 调试认证问题 |
|
||||
| auto-error-resolver | 自动修复 TypeScript 错误 |
|
||||
|
||||
**👉 [智能体工作原理 →](.claude/agents/README.md)**
|
||||
|
||||
### 💬 斜杠命令 (3)
|
||||
|
||||
| 命令 | 用途 |
|
||||
|---------|------|
|
||||
| /dev-docs | 创建结构化开发文档 |
|
||||
| /dev-docs-update | 在上下文重置前更新文档 |
|
||||
| /route-research-for-testing | 研究测试路由模式 |
|
||||
|
||||
---
|
||||
|
||||
## 核心概念
|
||||
|
||||
### 钩子 + skill-rules.json = 自动激活
|
||||
|
||||
**该系统：**
|
||||
1. **skill-activation-prompt 钩子** 在每个用户提示时运行
|
||||
2. 检查 **skill-rules.json** 中的触发模式
|
||||
3. 自动建议相关技能
|
||||
4. 仅在需要时加载技能
|
||||
|
||||
**这解决了 Claude Code 技能的第 1 号问题：** 它们不会自动激活。
|
||||
|
||||
### 渐进式披露（500 行规则）
|
||||
|
||||
**问题：** 大型技能会触及上下文限制
|
||||
|
||||
**解决方案：** 模块化结构
|
||||
- 主 SKILL.md < 500 行（概览 + 导航）
|
||||
- 资源文件每个 < 500 行（深入探讨）
|
||||
- Claude 根据需要增量加载
|
||||
|
||||
**示例：** backend-dev-guidelines 有 12 个资源文件，涵盖路由、控制器、服务、仓库、测试等。
|
||||
|
||||
### Dev Docs 模式
|
||||
|
||||
**问题：** 上下文重置会丢失项目上下文
|
||||
|
||||
**解决方案：** 三文件结构
|
||||
- `[task]-plan.md` - 战略计划
|
||||
- `[task]-context.md` - 关键决策和文件
|
||||
- `[task]-tasks.md` - 清单格式
|
||||
|
||||
**适用于：** `/dev-docs` 斜杠命令自动生成这些文件
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要：直接使用不会生效的内容
|
||||
|
||||
### settings.json
|
||||
包含的 `settings.json` 仅是**示例**：
|
||||
- Stop 钩子引用特定的 monorepo 结构
|
||||
- 服务名称（blog-api 等）是示例
|
||||
- MCP 服务器在您的设置中可能不存在
|
||||
|
||||
**使用方法：**
|
||||
1. 仅提取 UserPromptSubmit 和 PostToolUse 钩子
|
||||
2. 自定义或跳过 Stop 钩子
|
||||
3. 为您的设置更新 MCP 服务器列表
|
||||
|
||||
### 博客域示例
|
||||
技能使用通用博客示例（Post/Comment/User）：
|
||||
- 这些是**教学示例**，不是要求
|
||||
- 模式适用于任何域（电商、SaaS 等）
|
||||
- 将模式适配到您的业务逻辑
|
||||
|
||||
### 钩子目录结构
|
||||
一些钩子期望特定结构：
|
||||
- `tsc-check.sh` 期望服务目录
|
||||
- 基于您的项目布局进行自定义
|
||||
|
||||
---
|
||||
|
||||
## 集成工作流
|
||||
|
||||
**推荐方法：**
|
||||
|
||||
### 阶段 1：技能激活（15 分钟）
|
||||
1. 复制 skill-activation-prompt 钩子
|
||||
2. 复制 post-tool-use-tracker 钩子
|
||||
3. 更新 settings.json
|
||||
4. 安装钩子依赖
|
||||
|
||||
### 阶段 2：添加第一个技能（10 分钟）
|
||||
1. 选择 1 个相关技能
|
||||
2. 复制技能目录
|
||||
3. 创建/更新 skill-rules.json
|
||||
4. 自定义路径模式
|
||||
|
||||
### 阶段 3：测试和迭代（5 分钟）
|
||||
1. 编辑文件 - 技能应该激活
|
||||
2. 提问 - 应该建议技能
|
||||
3. 根据需要添加更多技能
|
||||
|
||||
### 阶段 4：可选增强
|
||||
- 添加您觉得有用的智能体
|
||||
- 添加斜杠命令
|
||||
- 自定义 Stop 钩子（高级）
|
||||
|
||||
---
|
||||
|
||||
## 获取帮助
|
||||
|
||||
### 对于用户
|
||||
**集成问题？**
|
||||
1. 查看 [CLAUDE_INTEGRATION_GUIDE.md](CLAUDE_INTEGRATION_GUIDE.md)
|
||||
2. 向 Claude 询问："为什么 [技能] 没有激活？"
|
||||
3. 提出包含您项目结构的问题
|
||||
|
||||
### 对于 Claude Code
|
||||
帮助用户集成时：
|
||||
1. **首先阅读 CLAUDE_INTEGRATION_GUIDE.md**
|
||||
2. 询问他们的项目结构
|
||||
3. 自定义，而不是盲目复制
|
||||
4. 集成后验证
|
||||
|
||||
---
|
||||
|
||||
## 这解决了什么问题
|
||||
|
||||
### 使用此基础设施前
|
||||
|
||||
❌ 技能不会自动激活
|
||||
❌ 必须记住使用哪个技能
|
||||
❌ 大型技能触及上下文限制
|
||||
❌ 上下文重置丢失项目知识
|
||||
❌ 开发中缺乏一致性
|
||||
❌ 每次都需要手动调用智能体
|
||||
|
||||
### 使用此基础设施后
|
||||
|
||||
✅ 技能根据上下文自动建议
|
||||
✅ 钩子在适当时机触发技能
|
||||
✅ 模块化技能保持在上下文限制内
|
||||
✅ Dev Docs 在重置后保留知识
|
||||
✅ 通过护栏实现一致的模式
|
||||
✅ 智能体简化复杂任务
|
||||
|
||||
---
|
||||
|
||||
## 社区
|
||||
|
||||
**觉得有用？**
|
||||
|
||||
- ⭐ 为这个仓库点星
|
||||
- 🐛 报告问题或建议改进
|
||||
- 💬 分享您自己的技能/钩子/智能体
|
||||
- 📝 从您的域贡献示例
|
||||
|
||||
**背景：**
|
||||
这套基础设施在我发布到 Reddit 的帖子["Claude Code is a Beast – Tips from 6 Months of Hardcore Use"](https://www.reddit.com/r/ClaudeAI/comments/1oivjvm/claude_code_is_a_beast_tips_from_6_months_of/)中有详细介绍。在收到数百个请求后，创建了这个展示库来帮助社区实施这些模式。
|
||||
|
||||
---
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT 许可证 - 在您的项目中自由使用，无论是商业项目还是个人项目。
|
||||
|
||||
---
|
||||
|
||||
## 快速链接
|
||||
|
||||
- 📖 [Claude 集成指南](CLAUDE_INTEGRATION_GUIDE.md) - 用于 AI 辅助设置
|
||||
- 🎨 [技能文档](.claude/skills/README.md)
|
||||
- 🪝 [钩子设置](.claude/hooks/README.md)
|
||||
- 🤖 [智能体指南](.claude/agents/README.md)
|
||||
- 📝 [Dev Docs 模式](dev/README.md)
|
||||
|
||||
**开始使用：** 复制两个必需钩子，添加一个技能，见证自动激活魔法发生。
|
||||
|
|
@ -0,0 +1,424 @@
|
|||
# Dev Docs 模式
|
||||
|
||||
一种在 Claude Code 会话和上下文重置之间维护项目上下文的方法论。
|
||||
|
||||
---
|
||||
|
||||
## 问题
|
||||
|
||||
**上下文重置会丢失一切：**
|
||||
- 实施决策
|
||||
- 关键文件及其用途
|
||||
- 任务进度
|
||||
- 技术约束
|
||||
- 为什么选择某些方法
|
||||
|
||||
**重置后，Claude 必须重新发现一切。**
|
||||
|
||||
---
|
||||
|
||||
## 解决方案：持久化开发文档
|
||||
|
||||
一个三文件结构，捕获继续工作所需的一切：
|
||||
|
||||
```
|
||||
dev/active/[task-name]/
|
||||
├── [task-name]-plan.md # 战略计划
|
||||
├── [task-name]-context.md # 关键决策和文件
|
||||
└── [task-name]-tasks.md # 清单格式
|
||||
```
|
||||
|
||||
**这些文件在上下文重置后仍然存在** - Claude 读取它们即可立即恢复状态。
|
||||
|
||||
---
|
||||
|
||||
## 三文件结构
|
||||
|
||||
### 1. [task-name]-plan.md
|
||||
|
||||
**用途：** 实施战略计划
|
||||
|
||||
**包含：**
|
||||
- 执行摘要
|
||||
- 当前状态分析
|
||||
- 提议的未来状态
|
||||
- 实施阶段
|
||||
- 带有验收标准的详细任务
|
||||
- 风险评估
|
||||
- 成功指标
|
||||
- 时间线估算
|
||||
|
||||
**何时创建：** 复杂任务开始时
|
||||
|
||||
**何时更新：** 范围变更或发现新阶段时
|
||||
|
||||
**示例：**
|
||||
```markdown
|
||||
# 功能名称 - 实施计划
|
||||
|
||||
## 执行摘要
|
||||
我们正在构建什么以及为什么
|
||||
|
||||
## 当前状态
|
||||
我们现在在哪里
|
||||
|
||||
## 实施阶段
|
||||
|
||||
### 阶段 1：基础设施（2 小时）
|
||||
- 任务 1.1：设置数据库模式
|
||||
- 验收：模式编译，关系正确
|
||||
- 任务 1.2：创建服务结构
|
||||
- 验收：所有目录已创建
|
||||
|
||||
### 阶段 2：核心功能（3 小时）
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. [task-name]-context.md
|
||||
|
||||
**用途：** 继续工作的关键信息
|
||||
|
||||
**包含：**
|
||||
- SESSION PROGRESS 部分（经常更新！）
|
||||
- 已完成与进行中的内容
|
||||
- 关键文件及其用途
|
||||
- 做出的重要决策
|
||||
- 发现的技术约束
|
||||
- 相关文件的链接
|
||||
- 快速恢复说明
|
||||
|
||||
**何时创建：** 任务开始时
|
||||
|
||||
**何时更新：** **经常** - 在重大决策、完成或发现之后
|
||||
|
||||
**示例：**
|
||||
```markdown
|
||||
# 功能名称 - 上下文
|
||||
|
||||
## SESSION PROGRESS (2025-10-29)
|
||||
|
||||
### ✅ 已完成
|
||||
- 数据库模式已创建（User、Post、Comment 模型）
|
||||
- PostController 已实施，使用 BaseController 模式
|
||||
- Sentry 集成正常工作
|
||||
|
||||
### 🟡 进行中
|
||||
- 创建具有业务逻辑的 PostService
|
||||
- 文件：src/services/postService.ts
|
||||
|
||||
### ⚠️ 阻碍
|
||||
- 需要决定缓存策略
|
||||
|
||||
## 关键文件
|
||||
|
||||
**src/controllers/PostController.ts**
|
||||
- 扩展 BaseController
|
||||
- 处理帖子的 HTTP 请求
|
||||
- 委托给 PostService
|
||||
|
||||
**src/services/postService.ts**（进行中）
|
||||
- 帖子操作的业务逻辑
|
||||
- 接下来：添加缓存
|
||||
|
||||
## 快速恢复
|
||||
要继续：
|
||||
1. 阅读此文件
|
||||
2. 继续实施 PostService.createPost()
|
||||
3. 查看任务文件了解剩余工作
|
||||
```
|
||||
|
||||
**关键：** 每次完成重要工作后更新 SESSION PROGRESS 部分！
|
||||
|
||||
---
|
||||
|
||||
### 3. [task-name]-tasks.md
|
||||
|
||||
**用途：** 跟踪进度的清单
|
||||
|
||||
**包含：**
|
||||
- 按逻辑部分分解的阶段
|
||||
- 复选框格式的任务
|
||||
- 状态指示符（✅/🟡/⏳）
|
||||
- 验收标准
|
||||
- 快速恢复部分
|
||||
|
||||
**何时创建：** 任务开始时
|
||||
|
||||
**何时更新：** 完成每个任务或发现新任务后
|
||||
|
||||
**示例：**
|
||||
```markdown
|
||||
# 功能名称 - 任务清单
|
||||
|
||||
## 阶段 1：设置 ✅ 完成
|
||||
- [x] 创建数据库模式
|
||||
- [x] 设置控制器
|
||||
- [x] 配置 Sentry
|
||||
|
||||
## 阶段 2：实施 🟡 进行中
|
||||
- [x] 创建 PostController
|
||||
- [ ] 创建 PostService（进行中）
|
||||
- [ ] 创建 PostRepository
|
||||
- [ ] 使用 Zod 添加验证
|
||||
|
||||
## 阶段 3：测试 ⏳ 未开始
|
||||
- [ ] 服务的单元测试
|
||||
- [ ] 集成测试
|
||||
- [ ] 手动 API 测试
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 何时使用开发文档
|
||||
|
||||
**用于：**
|
||||
- ✅ 复杂的多日任务
|
||||
- ✅ 有很多移动部分的功能
|
||||
- ✅ 可能跨越多个会话的任务
|
||||
- ✅ 需要仔细规划的工作
|
||||
- ✅ 重构大型系统
|
||||
|
||||
**跳过：**
|
||||
- ❌ 简单错误修复
|
||||
- ❌ 单文件更改
|
||||
- ❌ 快速更新
|
||||
- ❌ 琐碎修改
|
||||
|
||||
**经验法则：** 如果需要超过 2 小时或跨越多个会话，使用开发文档。
|
||||
|
||||
---
|
||||
|
||||
## 开发文档工作流程
|
||||
|
||||
### 开始新任务
|
||||
|
||||
1. **使用 /dev-docs 斜杠命令：**
|
||||
```
|
||||
/dev-docs 重构认证系统
|
||||
```
|
||||
|
||||
2. **Claude 创建三个文件：**
|
||||
- 分析需求
|
||||
- 检查代码库
|
||||
- 创建综合计划
|
||||
- 生成上下文和任务文件
|
||||
|
||||
3. **审查和调整：**
|
||||
- 检查计划是否合理
|
||||
- 添加任何缺失的考虑
|
||||
- 调整时间线估算
|
||||
|
||||
### 实施期间
|
||||
|
||||
1. **参考计划** 了解整体策略
|
||||
2. **频繁更新 context.md：**
|
||||
- 标记已完成的工作
|
||||
- 记录做出的决策
|
||||
- 添加阻碍
|
||||
3. **在 tasks.md 中勾选任务** 完成时
|
||||
|
||||
### 上下文重置后
|
||||
|
||||
1. **Claude 读取所有三个文件**
|
||||
2. **在几秒内理解完整状态**
|
||||
3. **从上次离开的确切位置继续**
|
||||
|
||||
无需解释您在做什么 - 一切都已记录！
|
||||
|
||||
---
|
||||
|
||||
## 与斜杠命令集成
|
||||
|
||||
### /dev-docs
|
||||
**创建：** 任务的新开发文档
|
||||
|
||||
**用法：**
|
||||
```
|
||||
/dev-docs 实施实时通知
|
||||
```
|
||||
|
||||
**生成：**
|
||||
- `dev/active/implement-real-time-notifications/`
|
||||
- implement-real-time-notifications-plan.md
|
||||
- implement-real-time-notifications-context.md
|
||||
- implement-real-time-notifications-tasks.md
|
||||
|
||||
### /dev-docs-update
|
||||
**更新：** 上下文重置前的现有开发文档
|
||||
|
||||
**用法：**
|
||||
```
|
||||
/dev-docs-update
|
||||
```
|
||||
|
||||
**更新：**
|
||||
- 标记已完成的任务
|
||||
- 添加发现的新任务
|
||||
- 使用会话进度更新上下文
|
||||
- 捕获当前状态
|
||||
|
||||
**使用时机：** 接近上下文限制或会话结束时
|
||||
|
||||
---
|
||||
|
||||
## 文件组织
|
||||
|
||||
```
|
||||
dev/
|
||||
├── README.md # 本文件
|
||||
├── active/ # 当前工作
|
||||
│ ├── task-1/
|
||||
│ │ ├── task-1-plan.md
|
||||
│ │ ├── task-1-context.md
|
||||
│ │ └── task-1-tasks.md
|
||||
│ └── task-2/
|
||||
│ └── ...
|
||||
└── archive/ # 已完成的工作（可选）
|
||||
└── old-task/
|
||||
└── ...
|
||||
```
|
||||
|
||||
**active/**：正在进行的工作
|
||||
**archive/**：已完成的任务（供参考）
|
||||
|
||||
---
|
||||
|
||||
## 示例：实际使用
|
||||
|
||||
查看此仓库中的 **dev/active/public-infrastructure-repo/** 了解真实示例：
|
||||
- **plan.md** - 创建此展示库的 700+ 行战略计划
|
||||
- **context.md** - 跟踪已完成内容、做出决策、下一步
|
||||
- **tasks.md** - 所有阶段和任务的清单
|
||||
|
||||
这是用于构建此展示库的实际开发文档！
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 频繁更新上下文
|
||||
|
||||
**不好：** 仅在会话结束时更新
|
||||
**好：** 在每个重要里程碑后更新
|
||||
|
||||
**SESSION PROGRESS 部分应始终反映现实：**
|
||||
```markdown
|
||||
## SESSION PROGRESS (YYYY-MM-DD)
|
||||
|
||||
### ✅ 已完成（列出完成的所有工作）
|
||||
### 🟡 进行中（您现在正在处理的工作）
|
||||
### ⚠️ 阻碍（阻止进度的工作）
|
||||
```
|
||||
|
||||
### 使任务可执行
|
||||
|
||||
**不好：** "修复认证"
|
||||
**好：** "在 AuthMiddleware.ts 中实施 JWT 令牌验证（验收：令牌验证，错误发送到 Sentry）"
|
||||
|
||||
**包括：**
|
||||
- 特定文件名
|
||||
- 清晰的验收标准
|
||||
- 对其他任务的依赖
|
||||
|
||||
### 保持计划最新
|
||||
|
||||
如果范围变更：
|
||||
- 更新计划
|
||||
- 添加新阶段
|
||||
- 调整时间线估算
|
||||
- 记录范围变更原因
|
||||
|
||||
---
|
||||
|
||||
## 对于 Claude Code
|
||||
|
||||
**当用户要求创建开发文档时：**
|
||||
|
||||
1. **如果可用，使用 /dev-docs 斜杠命令**
|
||||
2. **或手动创建：**
|
||||
- 询问任务范围
|
||||
- 分析相关代码库文件
|
||||
- 创建综合计划
|
||||
- 生成上下文和任务
|
||||
|
||||
3. **使用以下结构化计划：**
|
||||
- 清晰的阶段
|
||||
- 可执行的任务
|
||||
- 验收标准
|
||||
- 风险评估
|
||||
|
||||
4. **使上下文文件可恢复：**
|
||||
- 顶部的 SESSION PROGRESS
|
||||
- 快速恢复说明
|
||||
- 带说明的关键文件列表
|
||||
|
||||
**从开发文档恢复时：**
|
||||
|
||||
1. **阅读所有三个文件**（计划、上下文、任务）
|
||||
2. **从 context.md 开始** - 有当前状态
|
||||
3. **检查 tasks.md** - 了解已完成和待处理
|
||||
4. **参考 plan.md** - 了解整体策略
|
||||
|
||||
**频繁更新：**
|
||||
- 完成任务后立即标记
|
||||
- 重要工作后更新 SESSION PROGRESS
|
||||
- 发现新任务时添加
|
||||
|
||||
---
|
||||
|
||||
## 手动创建开发文档
|
||||
|
||||
如果您没有 /dev-docs 命令：
|
||||
|
||||
**1. 创建目录：**
|
||||
```bash
|
||||
mkdir -p dev/active/your-task-name
|
||||
```
|
||||
|
||||
**2. 创建 plan.md：**
|
||||
- 执行摘要
|
||||
- 实施阶段
|
||||
- 详细任务
|
||||
- 时间线估算
|
||||
|
||||
**3. 创建 context.md：**
|
||||
- SESSION PROGRESS 部分
|
||||
- 关键文件
|
||||
- 重要决策
|
||||
- 快速恢复说明
|
||||
|
||||
**4. 创建 tasks.md：**
|
||||
- 带复选框的阶段
|
||||
- [ ] 任务格式
|
||||
- 验收标准
|
||||
|
||||
---
|
||||
|
||||
## 好处
|
||||
|
||||
### 使用开发文档前
|
||||
- 上下文重置 = 重新开始
|
||||
- 忘记决策原因
|
||||
- 失去进度跟踪
|
||||
- 重复工作
|
||||
|
||||
### 使用开发文档后
|
||||
- 上下文重置 = 读取 3 个文件，立即恢复
|
||||
- 决策已记录
|
||||
- 进度已跟踪
|
||||
- 无重复工作
|
||||
|
||||
**节省的时间：** 每次上下文重置数小时
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
1. **在下一次复杂任务中尝试此模式**
|
||||
2. **使用 /dev-docs** 斜杠命令（如果可用）
|
||||
3. **频繁更新** - 特别是 context.md
|
||||
4. **查看实际操作** - 浏览 dev/active/public-infrastructure-repo/
|
||||
|
||||
**有疑问？** 查看 [CLAUDE_INTEGRATION_GUIDE.md](../CLAUDE_INTEGRATION_GUIDE.md)
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
医生在6400公里外进行脑部手术 + 9条其他新闻
|
||||
|
||||
2025/11/12 00:37:07
|
||||
|
||||
在过去4天里，ChatGPT阅读了126822条头条新闻。去除此前已报道的事件后，有10篇文章的重要性评分超过5.5。
|
||||
|
||||
[5.6] 外科医生远程控制机器人移除脑部血块 — bbc.com (+6)
|
||||
|
||||
首次实现了跨大西洋机器人血栓切除术，外科医生在6400公里外移除了一具尸体的脑部血块，这是一项重大医学突破。
|
||||
|
||||
佛罗里达州的一位神经外科医生远程控制了位于苏格兰的机器人，体验到的延时极小。该技术旨在克服专家短缺问题，为偏远地区的患者提供紧急中风治疗，因为在偏远地区治疗时间至关重要。
|
||||
|
||||
[5.9] 中国免除安世半导体芯片出口管制，缓解欧洲汽车生产担忧 — bbc.com (+17)
|
||||
|
||||
中国取消了安世计算机芯片的出口管制，避免了依赖这些组件的欧洲汽车工厂可能出现停产的风险。
|
||||
|
||||
这一决定扭转了中国在10月份荷兰政府接管这家总部位于荷兰的中资公司后实施封锁的局面。汽车制造商此前警告他们的芯片供应即将耗尽。
|
||||
|
||||
尽管安世半导体总部位于荷兰，但其许多芯片在中国完成加工后再出口。官员们目前正在制定稳定的框架，以确保半导体流通的全面恢复。
|
||||
|
||||
重要性超过5.5的高度关注新闻
|
||||
|
||||
[6.4] 叙利亚总统访问白宫，讨论加入美国主导的联盟 — ici.radio-canada.ca（法语）（+116）
|
||||
|
||||
[5.5] 美国参议院通过协议结束政府停摆 — bbc.com (+351)
|
||||
|
||||
[5.7] 美国接管以色列在加沙的援助管理 — ilmessaggero.it（意大利语）（+2）
|
||||
|
||||
[5.9] OpenAI面临七项诉讼，指控ChatGPT导致用户自杀和精神错乱 — capitalgazette.com (+19)
|
||||
|
||||
[5.8] 慕尼黑法院裁定ChatGPT未经许可不得使用歌词 — tagesschau.de（德语）（+9）
|
||||
|
||||
[6.1] 香港科学家开发高速成像技术，用于活体小鼠脑细胞活动观察 — medicalxpress.com (+2)
|
||||
|
||||
[5.5] 都柏林三一学院研究人员开发出阻断传播的百日咳疫苗 — irishexaminer.com (+3)
|
||||
|
||||
[6.0] CRISPR基因编辑疗法在首次人体试验中安全降低胆固醇和甘油三酯 — newsroom.heart.org (+26)
|
||||
|
||||
感谢阅读！
|
||||
|
||||
— Vadim
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
# 知性是否会再次浮上
|
||||
|
||||
## 杂志更迭的无意义时代
|
||||
|
||||
继上次之后，我们继续阅读桥本治于1994年出版的《浮上せよと活字は言う》（文字说必须浮上来）。这本书是桥本治关于书籍的论述，也是关于出版的论述。其中有许多篇幅论述了自1970年代后半期以来发生决定性巨变的杂志。
|
||||
|
||||
众所周知，1980年代被称为"杂志的时代"。但这个时代不仅诞生了许多杂志，停刊的杂志也很多。如果意义已失的旧杂志消失，由承担新意义的杂志依次诞生，那倒也不错，但这个时代创刊的许多杂志也没能稳定地获得读者支持，早早便消失了。关于这种情况，桥本是这样论述的：
|
||||
|
||||
"准确地说，1980年代并非'杂志的时代'。1980年代是'杂志更迭的时代'，是'杂志更迭的无意义的时代'。新杂志创刊数量的多，以及停刊杂志数量的多，都证明了这一点。在1980年代，杂志这种东西发生了改变，而在改变这一点上可以说是相当失败的。"（"排除愚蒙"）
|
||||
|
||||
自1970年代后半期以来，综合杂志（正如桥本文章连载的《中央公论》自身）所象征的权威"文字"失去意义，读者支持丧失的时代到来了。在这样的背景下新创刊，并例外地持续取得大规模成功的杂志有两本。《POPEYE》（Magazine House，1976年创刊）和《JJ》（光文社，1975年创刊）。桥本在《浮上せよと活字は言う》中用大半篇幅论述这两本杂志为出版界带来的变化的意义。这份热度在今天读来令人感到不可思议。
|
||||
|
||||
### 在"旧分类"中无法把握"新意义"
|
||||
|
||||
在论述两本杂志的具体特征之前，桥本首先将目光投向当时的出版业界是如何分类杂志的。《POPEYE》和《JJ》都具备了可称为"时尚杂志"的内容。但1980年当时出版业界的"杂志统计分析"中并没有"时尚杂志"这一独立部门。据桥本引用，当时杂志被分为以下25个部门：
|
||||
|
||||
儿童・妇女・大众・综合・文艺・演艺・美术・音乐・生活・趣味・体育・经济・社会・时局・哲学・学参（学习参考书）・语言・教育・地历・法律・科学・工学・医学・农水・周刊杂志
|
||||
|
||||
桥本评价这个分类为"像役所的科室和大学的学部列表中被附上了'周刊杂志'这个不可思议的东西"，可谓一语中的。例如，这个列表中有"妇女"但没有"女性（杂志）"或"时尚（杂志）"的区分。（顺便说一下，现在日本杂志协会这样分类杂志的体裁。要说是"多样化"的话倒也可以，但分类标准的混乱似乎反而增加了）
|
||||
|
||||
"自1970年代后半期迎来新杂志创刊热潮的出版界，首先应该思考的是，他们是在这种不可思议的分类项目下把握世界这件事的古旧。这种思维方式是旧的，所以新杂志必须登场，必须以'杂志的时代'这一形式，让杂志='大众性的东西'成为焦点。"（同上）
|
||||
|
||||
这样思考的桥本认为，《POPEYE》和《JJ》正是体现了这个时代的"大众性的东西"的杂志。
|
||||
|
||||
那么，为什么这两本杂志具有划时代的意义呢？桥本认为《POPEYE》起到了"驱逐文字的意义"的作用，《JJ》起到了"从社会中驱逐纪律"的作用。两者的共同点在于"出色地反映了读者的声音"，"并且由此甚至做到了放弃编辑权这样的绝技"（"论断绝"）。两本杂志以"时尚"这一形式体现了当时的"现实"，而不知道这一现实的"知性"在那现实面前失败了——桥本如此断言。
|
||||
|
||||
### 专栏化的"文字"从主角位置退下
|
||||
|
||||
这些杂志给"文字"带来的最大变化是，所有文章的专栏化。在日本出版业界被称为"专栏"的，指的是失去了column原本具有的"论说"这一语感的"短文围栏文章"。
|
||||
|
||||
在《POPEYE》和《JJ》之后，更准确地说是在《an・an》之后出现的视觉中心的"看杂志"中，图形设计师预先精密地构成版面，进行所谓的"预分配"进行排版。在这里，"文字"失去了使杂志成立的主角地位，仅仅成为填满规定字数格子的"部件（parts）"。同样是和制英语的"Writer"，是指被订购生产作为杂志中部件文本的供货商。
|
||||
|
||||
尽管如此，桥本本人并非立即批判语言（文字）被设计和图形置于从属地位这一事实。桥本自身在作家出道前是插画师，在以少女漫画为代表的视觉表现中读出了新的意义和希望。而且桥本自身当时为新诞生的各种"新杂志"撰写了众多"专栏"（甚至有讽刺当时专栏热潮的著作《David100专栏》）。
|
||||
|
||||
《POPEYE》和《JJ》的登场，蕴含着凭借旧"文字"无法把握的各种新的"意义"。但这些新的"意义"很长时间未能被语言把握，因此也未能在社会中得到正当定位，可能性始终只是可能性，未能结出果实而枯萎了。桥本在《浮上せよと活字は言う》中如此论述。
|
||||
|
||||
在《POPEYE》和《JJ》之中，之后经常被讨论、相关人士证言也丰富留存下来的是《POPEYE》。代表性著作有，作为初期编辑部成员参与的椎根和的《POPEYE物语——改变年轻人的传说杂志》（新潮文库），以及作为该杂志爱读者的赤田祐一的《证言构成〈POPEYE〉的时代——某杂志的奇妙航海》（太田出版）。包括围绕孕育了该杂志的出版社Magazine House（平凡出版）的书在内，不可胜数。所以在这里，我想论述一下之后不太被提及的《JJ》，以及桥本的论述及其之后的发展。
|
||||
|
||||
### "搭配"这一实用性知性
|
||||
|
||||
桥本在《JJ》的什么地方看到了新意呢？这通过与该杂志之前、先锐的女性时尚杂志先驱《an・an》的对比如下说明：
|
||||
|
||||
"如果那是'新思想'的话，情况对文字人类来说还是能够把握的。但《JJ》并非思想杂志。被称为'目录杂志'的，仅仅是时尚杂志。'所有一切都已在那里，因此需要秩序（搭配）'这一思想，仅此而已，从切碎的照片之中能够看到。"（"三度论断绝"）
|
||||
|
||||
这里被称为"思想杂志"的是《an・an》。的确，《an・an》为女性时尚杂志的应有方式带来了一场革命。但是，这本先锐杂志提示的"思想"，对许多日本女性来说是"现实中没有用处"的。从这个意义上说，外来的最新思想，对大半日本男性来说也是难以切身体会的。
|
||||
|
||||
与此相对，《JJ》为过去各个时代的"思想=时尚"流行所带来的死库存式积累——对男性来说如同"积压的未读书"般的未被使用的知性——提供了以一枚围巾的使用方法为象征的"搭配/秩序"这一"实用性"。由此，《JJ》从时尚中放逐了以"样式"这一形式存在的传统"纪律"，桥本如是说。
|
||||
|
||||
无纪律的传统被称为"中性"（neutral）并得到一般化，同时为日本的平凡的——正如被称为"保守"的那样，也是保守的——女性们带来了"思考就是具体地考虑如何处理这个现实"这一智慧。"然后，就那样直接到哪里去了"。
|
||||
|
||||
另外，《浮上せよと活字は言う》中桥本治这样写道以来，已经过了近30年。《POPEYE》之后经过数次方向转换，作为比"年轻人"更加成熟的"文字"喜欢的青年向专栏杂志存续着。另一方面，《JJ》在互联网和SNS时代正式到来之中急剧减少发行量，2021年2月号宣布改为不定期刊行并向网络媒体迁移。作为纸质媒体事实上休刊了。
|
||||
|
||||
在《JJ》休刊被报道后，1990年代作为该杂志热心读者的作家铃木凉美撰写了《JJ与其时代 女孩子向杂志梦想着什么》（光文社新书）。本书不仅是切实的、体验式的优秀《JJ》论，也是《JJ》与其同时代女性时尚杂志论，是普世的杂志论。桥本叹息"就那样直接到哪里去了"之后，"到哪里去了"的东西，即年轻女性们现实的"语言"曾长期缺席。如果终于能够通过"文字"把握那现实的话，新的知性或许也能从那里"浮上"。
|
||||
|
||||
## 正文登场书籍一览
|
||||
|
||||
《POPEYE物语——改变年轻人的传说杂志》 作者：椎根和（新潮文库 2010年）
|
||||
《证言构成〈POPEYE〉的时代——某杂志的奇妙航海》 作者：赤田祐一（太田出版 2016年）
|
||||
《增补 浮上せよと活字は言う》 作者：桥本治（平凡社Library 2002年）
|
||||
《JJ与其时代 女孩子向杂志梦想着什么》 作者：铃木凉美（光文社新书 2021年）
|
||||
|
||||
（本文是2022年2月在Modern Times公开的文章的再刊）
|
||||
Loading…
Reference in New Issue