learn-codebase

学习代码库约定

扫描当前项目中的各类工具 Agent 指令文件，总结其中的约定，并可选择将发现的技能注册到 .pi/settings.json。

第 1 步：扫描约定文件

在项目根目录中搜索以下文件和目录：

# Agent instruction files (root-level)
for f in CLAUDE.md AGENTS.md COPILOT.md .cursorrules .clinerules; do
  [ -f "$f" ] && echo "FOUND: $f"
done

# Agent config directories
for d in .claude .cursor .github .pi; do
  [ -d "$d" ] && echo "FOUND DIR: $d/"
done

# Deeper convention files
[ -f ".github/copilot-instructions.md" ] && echo "FOUND: .github/copilot-instructions.md"

# Claude Code rules, skills, and commands
[ -d ".claude/rules" ] && echo "FOUND: .claude/rules/"
[ -d ".claude/skills" ] && echo "FOUND: .claude/skills/"
[ -d ".claude/commands" ] && echo "FOUND: .claude/commands/"

# Cursor rules
[ -d ".cursor/rules" ] && echo "FOUND: .cursor/rules/"

# Pi project skills
[ -d ".pi/skills" ] && echo "FOUND: .pi/skills/"

第 2 步：阅读并总结

对于发现的每个文件，阅读其内容并提取关键约定：

1. 根目录指令文件（CLAUDE.md、AGENTS.md、.cursorrules 等）——完整阅读，这些是项目的主要规则
2. 规则目录（.claude/rules/、.cursor/rules/）——阅读每个规则文件
3. 命令（.claude/commands/）——阅读每个命令文件。这些是 Claude Code 中可重复使用的提示词工作流（例如 PR 创建、发布脚本、审查清单）。总结每个命令的用途。
4. 技能目录（.claude/skills/、.cursor/skills/）——列出可用技能并阅读其说明
5. 设置文件（.claude/settings.json）——记录权限和配置

向用户提供结构化总结：

## Project Conventions Summary

### Build & Run
- Package manager: [npm/pnpm/yarn/bun]
- Dev command: [command]
- Test command: [command]

### Code Style
- [Key style rules]

### Architecture
- [Key patterns, structure]

### Agent-Specific Rules
- [Any rules targeted at AI agents]

### Available Commands (from .claude/commands/)
- [command-name] — [what it does]

### Available Skills (from other tools)
- [List skills found in .claude/skills, .cursor/skills]

聚焦于可执行的信息。跳过样板内容和显而易见的约定。

第 3 步：注册外部技能

如果存在 .claude/skills/ 或其他技能目录，建议将其注册到 .pi/settings.json，以便 pi 也能使用这些技能：

{
  "skills": ["../.claude/skills"]
}

询问用户是否要使用发现的技能路径创建或更新 .pi/settings.json。只有在确实发现技能时才执行此操作。

第 4 步：指出需要牢记的事项

总结后，重点列出在此项目中工作时最需要牢记的 3-5 项内容。这些是最容易被忽略的约定，例如：

• 特定的提交消息格式
• 必须包含的共同作者行
• 强制要求的测试模式
• 禁止的模式或反模式
• 包管理器偏好（要求使用 pnpm 时，不要使用 npm）

第 5 步：安全与问题快速排查

扫描代码库，查找看起来可疑、诡异或危险的内容。这不是完整审计，而是快速排查，旨在提醒用户注意潜在问题。指出真实风险，不要臆测。

扫描内容

运行以下检查并报告任何可疑之处：

硬编码的密钥和凭据

# Look for hardcoded secrets, API keys, tokens, passwords
rg -i --hidden -g '!{.git,node_modules,dist,build,.next,vendor,*.lock}' \
  '(api[_-]?key|secret|token|password|credential|auth)\s*[:=]\s*["\x27][^"\x27]{8,}' \
  --type-not binary -l 2>/dev/null | head -20

# .env files committed to repo (should be gitignored)
git ls-files --cached | grep -iE '\.env($|\.)' 2>/dev/null

不安全的代码模式

# eval(), exec(), dangerouslySetInnerHTML, innerHTML assignments, shell injection vectors
rg --hidden -g '!{.git,node_modules,dist,build,.next,vendor,*.lock}' \
  -e '\beval\s*\(' -e '\bexec\s*\(' -e 'dangerouslySetInnerHTML' \
  -e '\.innerHTML\s*=' -e 'child_process' -e '\$\(.*\$\{' \
  --type-not binary -l 2>/dev/null | head -20

# Unparameterized SQL (string concatenation in queries)
rg --hidden -g '!{.git,node_modules,dist,build,.next,vendor,*.lock}' \
  -e 'query\s*\(\s*[`"'"'"'].*\$\{' -e 'execute\s*\(\s*[`"'"'"'].*\+' \
  --type-not binary -l 2>/dev/null | head -20

可疑的依赖项

# Check for install/postinstall scripts in dependencies (supply chain risk)
[ -f package.json ] && cat package.json | grep -E '"(pre|post)install"' 2>/dev/null

# Look for wildcard or git dependencies (unpinned)
[ -f package.json ] && rg '"[*]"|"git[+:]|"github:' package.json 2>/dev/null

# Very outdated lock file vs package.json mismatch
[ -f package-lock.json ] && [ package.json -nt package-lock.json ] && echo "WARN: package.json newer than lockfile"
[ -f pnpm-lock.yaml ] && [ package.json -nt pnpm-lock.yaml ] && echo "WARN: package.json newer than lockfile"

权限过于宽松的配置

# CORS wildcards, disabled security headers, permissive CSP
rg --hidden -g '!{.git,node_modules,dist,build,.next,vendor,*.lock}' \
  -e "origin:\s*['\"]?\*" -e 'Access-Control-Allow-Origin.*\*' \
  -e "cors.*true" -e 'unsafe-inline' -e 'unsafe-eval' \
  --type-not binary -l 2>/dev/null | head -10

# Disabled TLS verification, insecure flags
rg --hidden -g '!{.git,node_modules,dist,build,.next,vendor,*.lock}' \
  -e 'NODE_TLS_REJECT_UNAUTHORIZED.*0' -e 'rejectUnauthorized.*false' \
  -e 'verify.*false' -e 'insecure.*true' \
  --type-not binary -l 2>/dev/null | head -10

文件权限和敏感文件

# Private keys, certificates, or database files in repo
git ls-files --cached 2>/dev/null | grep -iE '\.(pem|key|p12|pfx|jks|keystore|sqlite|db)$' | head -10

# Check .gitignore exists and covers basics
if [ -f .gitignore ]; then
  for pattern in '.env' 'node_modules' '.DS_Store'; do
    grep -q "$pattern" .gitignore || echo "WARN: .gitignore missing $pattern"
  done
else
  echo "WARN: No .gitignore file found"
fi

报告方式

在专门的章节中使用严重性标签呈现发现。直截了当，不要粉饰，但也不要误报。

## 🚩 Security & Code Smell Findings

### [P0] Hardcoded API key in src/config.ts
Line 42 has a Stripe secret key directly in source code.
This should be in an environment variable, not committed.

### [P1] .env file tracked by git
`.env.production` is committed and contains database credentials.
Add to `.gitignore` and rotate the exposed credentials.

### [P2] eval() usage in src/utils/parser.ts
Used to parse user-supplied expressions. Consider a safe parser
like `JSON.parse()` or a sandboxed evaluator instead.

### ✅ Nothing Concerning
[If sweep is clean, say so explicitly — don't manufacture findings.]

严重性指南（与审查标准相同）：

• [P0] — 目前就具有危险性。密钥暴露、SQL 注入、RCE 攻击途径。立即修复。
• [P1] — 存在真实风险，迟早会造成问题。应尽快修复。
• [P2] — 值得了解，不紧急，但用户应该注意。

请勿标记：

• 为测试目的而使用 eval/exec 的测试文件
• 已知仅用于开发环境的不安全配置（例如开发服务器中的 localhost CORS）
• 在此代码库中没有具体利用途径的理论问题
• 仅仅较旧的依赖项（若没有已知 CVE，就不构成安全问题）