1k-code-quality

コード品質

OneKey の lint、ドキュメント、および一般的なコード品質の標準です。

Lint コマンド

# Agent pre-commit gate (fast, only staged files)
yarn agent:check --profile commit

# Agent PR readiness gate (local staged checks + GitHub CI/review summary)
yarn agent:check --profile pr

# CI only (full project check)
yarn lint        # Comprehensive: TypeScript, oxlint, folder structure, i18n
yarn lint:only   # Oxlint and oxfmt
yarn tsc:only    # Full type check
yarn lint:agent-context # Skill metadata and startup-context budgets

注： yarn lint は CI 専用です。エージェントのワークフローでは、必ず最初に yarn agent:check を使用してください。agent:check が報告したログ パスをデバッグする場合に限り、低レベルのコマンドを使用してください。

このリポジトリでは、アクティブな lint 検証に ESLint ではなく oxlint を使用します。 yarn eslint、npx eslint、node_modules/.bin/eslint は実行しないでください。これらは レガシー互換用の残存物であり、yarn eslint はリポジトリ全体に対して 自動修正を実行します。読み取り専用の対象を絞った診断を行うには、次を実行してください。

npx oxlint --tsconfig ./tsconfig.json --type-aware packages/example/src/file.ts --deny-warnings

コミット前のワークフロー

コミット前の迅速な検証には、次を実行してください。

yarn agent:check --profile commit

よくある Lint の修正

// Unused variable - prefix with underscore
const { used, unused } = obj;     // ❌ Error: 'unused' is defined but never used
const { used, unused: _unused } = obj;  // ✅ OK

// Unused parameter - prefix with underscore
function foo(used: string, unused: number) {}     // ❌ Error
function foo(used: string, _unused: number) {}    // ✅ OK

// Floating promise - add void or await
someAsyncFunction();        // ❌ Error: Promises must be awaited
void someAsyncFunction();   // ✅ OK (fire-and-forget)
await someAsyncFunction();  // ✅ OK (wait for result)

言語要件

コメントはすべて英語で記述してください。

// ✅ GOOD: English comment
// Calculate the total balance including pending transactions

// ❌ BAD: Chinese comment
// 计算总余额，包括待处理的交易

// ✅ GOOD: JSDoc in English
/**
 * Fetches user balance from the blockchain.
 * @param address - The wallet address to query
 * @returns The balance in native token units
 */
async function fetchBalance(address: string): Promise<bigint> {
  // ...
}

コメントを記述する場合

// ✅ GOOD: Explain non-obvious logic
// Use 1.5x gas limit to account for estimation variance on this chain
const gasLimit = estimatedGas * 1.5n;

// ✅ GOOD: Explain business logic
// Premium users get 50% discount on transaction fees
const fee = isPremium ? baseFee * 0.5 : baseFee;

// ❌ BAD: Obvious comment
// Set the value to 5
const value = 5;

開発原則

単一責任

各関数は、単一の独立したタスクを実行する必要があります。

// ✅ GOOD: Single responsibility
async function fetchUserBalance(userId: string): Promise<Balance> {
  const user = await getUser(userId);
  return await getBalanceForAddress(user.address);
}

// ❌ BAD: Multiple responsibilities
async function fetchUserBalanceAndUpdateUI(userId: string) {
  const user = await getUser(userId);
  const balance = await getBalanceForAddress(user.address);
  setBalanceState(balance);
  showNotification('Balance updated');
  logAnalytics('balance_fetched');
}

過度な抽象化を避ける

一度限りの処理のためにヘルパーを作成しないでください。

// ❌ BAD: Over-abstracted
const createUserFetcher = (config: Config) => {
  return (userId: string) => {
    return fetchWithConfig(config, `/users/${userId}`);
  };
};
const fetchUser = createUserFetcher(defaultConfig);
const user = await fetchUser(userId);

// ✅ GOOD: Simple and direct
const user = await fetch(`/api/users/${userId}`).then(r => r.json());

詳細ガイド

コード品質の標準

包括的なガイドラインについては、code-quality.md を参照してください。

• Lint コマンドとコミット前のワークフロー
• コメントとドキュメントの標準
• 言語要件（英語のみ）
• 単一責任の原則
• 過度な抽象化の回避
• 一貫した命名規則
• コード品質チェックリスト

Lint 警告の修正

Lint 修正のワークフロー全体については、fix-lint.md を参照してください。

• Lint 警告の分析
• Lint エラーの分類
• カテゴリ別の一般的な修正パターン
• スペルチェックの修正
• 未使用の変数／パラメーターの処理
• 自動修正の方法
• 修正後のテスト

スペルチェック

技術用語がスペルチェックエラーの原因となる場合：

# Check if word exists
grep -i "yourword" development/spellCheckerSkipWords.txt

# Add if not present (ask team lead first)
echo "yourword" >> development/spellCheckerSkipWords.txt

エージェントコンテキストハーネス

yarn lint:agent-context は、リポジトリ内のスキルの検出と起動時のコンテキスト予算を 適用します。設定は development/lint/agent-context.config.json にあります。スキルを追加または再構成する場合は、 詳細なガイダンスをリファレンスに記載し、運用ワークフローには Codex の明示的なポリシーを 使用して、設定されたカタログと指示の予算内に収めてください。

チェックリスト

コミット前

• yarn agent:check --profile commit が成功する

コード品質

• コメントがすべて英語で記述されている
• コメントアウトされたコードをコミットしていない
• 関数が単一責任を持つ
• 不要な抽象化がない
• 命名規則に一貫性がある

関連スキル

• /1k-sentry - Sentry のエラー分析と修正
• /1k-test-version - テストバージョン作成のワークフロー
• /1k-coding-patterns - 一般的なコーディングパターン